maz

Microsoft Azure library module for simple MSAL authentication, and calling MS Graph and Azure resource APIs. Other APIs could be added in the future.

WARNING: Currently under constant changes.

Getting Started

1. Any program or utility wanting to use this libray module can simply import it, then instantiate a variable of type maz.Bundle to manage the interaction. For example:

import (
    "github.com/git719/maz"
)
z := maz.Bundle{
    ConfDir:      "",                   // Set up later, see example below
    CredsFile:    "credentials.yaml",
    TokenFile:    "accessTokens.json",
    TenantId:     "",
    ClientId:     "",
    ClientSecret: "",
    Interactive:  false,
    Username:     "",
    AuthorityUrl: "",                   // Set up later with maz.ConstAuthUrl + z.TenantId (see const block in maz.go)
    MgToken:      "",                   // Set up below 4 later with function maz.SetupApiTokens()
    MgHeaders:    map[string]string{},
    AzToken:      "",
    AzHeaders:    map[string]string{},  
}
// Then update the variables within the Bundle, to set up configuration directory
z.ConfDir = filepath.Join(os.Getenv("HOME"), "." + prgname)
if utl.FileNotExist(z.ConfDir) {
    if err := os.Mkdir(z.ConfDir, 0700); err != nil {
        panic(err.Error())
    }
}

2. Then call maz.SetupInterativeLogin(z) or maz.SetupAutomatedLogin(z) to setup the credentials file accordingly.
3. Then call z := maz.SetupApiTokens(*z) to acquire the respective API tokens, web headers, and other variables.
4. Now call whatever MS Graph and Azure Resource API functions you want by passing and using the z variables, with its z.mgHeaders and/or z.azHeaders attributes, and so on.

Login Credentials

There are four (4) different ways to set up the login credentials to use this library module. All four ways required three (3) special attributes:

#	Type	Method	Details
1	Interactive	Config file	Set up attributes via ~/.maz/credentials.yaml file
2	Interactive	Environment variables	Set up attributes via environment variables (OVERIDES config file)
3	Automated	Config file	Set up attributes via ~/.maz/credentials.yaml file
4	Automated	Environment variables	Set up attributes via environment variables (OVERIDES config file)

1. Interactive via config file: The calling utility sets up a way to allow setting up the ~/.maz/credentials.yaml file with the 3 special attributes. For example, the zls CLI utility does this via the -cri switch, to Set up MSAL interactive browser popup login:

   zls -cri 3f050090-20b0-40a0-a060-c05060104010 [email protected]
   

   Above will populate the ~/.maz/credentials.yaml file as follows:

   tenant_id: 3f050090-20b0-40a0-a060-c05060104010
   username: [email protected]
   interactive: true
   

   From then on the zls utility will use above credentials to interact with the maz library to perform all its functions.
2. Interactive via environment variables: The calling utility will instead use the os.Getenv("VAR") function to look for the following 3 special environment variables:

   MAZ_TENANT_ID=3f050090-20b0-40a0-a060-c05060104010
   [email protected]
   MAZ_INTERACTIVE=true
   

   Above values take precedence and OVERIDE any existing config ~/.maz/credentials.yaml file values.
3. Automated via config file: The calling utility sets up a way to allow setting up the ~/.maz/credentials.yaml file with the 3 special attributes. For example, the zls CLI utility does this via the -cr switch, to Set up MSAL automated ClientId + Secret login:

   zls -cr 3f050090-20b0-40a0-a060-c05060104010 f1110121-7111-4171-a181-e1614131e181 ACB8c~HdLejfQGiHeI9LUKgNOODPQRISNTmVLX_i
   

   Above will populate the ~/.maz/credentials.yaml file as follows:

   tenant_id: 3f050090-20b0-40a0-a060-c05060104010
   client_id: f1110121-7111-4171-a181-e1614131e181
   client_secret: ACB8c~HdLejfQGiHeI9LUKgNOODPQRISNTmVLX_i
   

   From then on the zls utility will use above credentials to interact with the maz library to perform all its functions.
4. Automated via environment variables: The calling utility will instead use the os.Getenv("VAR") function to look for the following 3 special environment variables

   MAZ_TENANT_ID=3f050090-20b0-40a0-a060-c05060104010
   MAZ_CLIENT_ID=f1110121-7111-4171-a181-e1614131e181
   MAZ_CLIENT_SECRET=ACB8c~HdLejfQGiHeI9LUKgNOODPQRISNTmVLX_i
   

   Above values take precedence and OVERIDE any existing config ~/.maz/credentials.yaml file values.

The benefit of using environment variables is of course to be able to override an existing credentials.yaml file, and specify different credentials, as well as being able to do this from different shell sessions on the same host. They also allow utilities written with this library to be more used in continuous delivery and other types of automation.

NOTE: If all four MAZ_USERNAME, MAZ_INTERACTIVE, MAZ_CLIENT_ID, and MAZ_CLIENT_SECRET are properly define, then precedence is given to the Username Interactive login. To force a ClientID ClientSecret login via environment variables, you must ensure the first two are unset in the current shell.

Functions

List of all available functions.

• maz.SetupInterativeLogin: This functions allows you to set up the~/.maz/credentials.yaml file for interactive Azure login.

TODO: List other functions here ...