Token Authentication

The standard authentication method used by the Nectar PowerShell module is Basic Authentication. This works well for local Nectar accounts, but does not work for SSO accounts.

Nectar DXP now offers JSON Web Token (JWT) authentication, which works for both local and SSO accounts. Using JWT authentication requires some additional configuration on machines that will be using this feature.

Generating a Token

1. Login to Nectar DXP using your normal account (local or SSO).

2. Click on your email address on the top-right and select Account Settings

3. Scroll to the API TOKEN AUTHENTICATION section at the bottom.

4. Click on the Generate API Access Token button.

5. Create a meaningful name and (optionally) select a validity period, then click GENERATE.

   

6. Copy the access and refresh token values and store them somewhere safe. They will not be shown again.

Using Tokens in the Nectar DXP PowerShell Module

The Nectar DXP PowerShell module depends on the Microsoft Secret Management PowerShell module for secret storage and access. This module allows users to utilize secrets stored in a variety of platforms, ranging from local machine (via SecretStore) to centralized remote secret managers such as Keeper and Azure KeyVault using a standard set of commands. Users first install the MS Secret Management module, then add on additional secret store modules that plug into various secret management platforms.

Install the MS Secret Management PS Module

From a PowerShell command window, type:

Install-Module Microsoft.PowerShell.SecretManagement

This installs the framework that the Nectar PS module uses for securely accessing secrets. To actually use secrets, a secret store of some kind is required, as documented in the next section.

Install the SecretStore PS Module

For this example, we will use the locally stored secret store via Microsoft.SecretStore. Other secret stores will require additional steps that are outside the scope of this article. A list of available secret stores is available here.

Install-Module Microsoft.PowerShell.SecretStore

Create a Default Secret Vault

Once the Microsoft SecretStore module is installed, you must create a secret vault to store your secrets. The below command will create a vault using the Microsoft SecretStore module and set it as the default vault.

Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault

Create a Secret for Nectar PS Module Usage

The Nectar PS Module is designed to use secrets that are named according to the FQDN of the Nectar DXP environment along with “-accesstoken” appended to the end. Example: us.nectar.services-accesstoken The Nectar PS Module makes creating secrets easy by using the New-NectarTokenRegistration command.

New-NectarTokenRegistration -CloudFQDN <YourCloudFQDN> -AccessToken <YourSavedAccessToken> -RefreshToken <YourSavedRefreshToken> -DomainName <YourEmailDomain>

Example:

New-NectarTokenRegistration -CloudFQDN us.nectar.services -AccessToken 23fdsgvb34lkwe098fdskj32asfd9745 -RefreshToken k239dfslm34289dfhgfd874hfgd -DomainName contoso.com

This will create an secret in the default secret store called us.nectar.services-accesstoken.  Read the documentation for New-NectarTokenRegistration for additional parameters.

Using a Secret in Nectar DXP PS Module

Once the secret has been created, you can use it to log into Nectar DXP, instead of using local credentials. Use this format for logging in via Connect-NectarCloud:

Connect-NectarCloud us.nectar.services -UseToken

This will log you into https://us.nectar.services using the secret called us.nectar.services-accesstoken

Error Handling

If you are encountering an “(Error 500') Internal Service Error“, enter the code below into your window, then try to reconnect.

Disconnect-NectarCloud

Using Tokens for API Access

If you wish to use tokens for direct API access via methods other than PowerShell, here are some pointers.

Every API call requires an authorization header consisting of the access token in the following format:

{
	'authorization'		= "Bearer <AccessToken>"
}

Refresh tokens expire after 2 hours, after which API requests will fail with a 401 error code.

To renew the token, pass the following header via POST to https://<CloudFQDN>/aapi/jwt/token/renew:

{
	'x-refresh-token' = <RefreshToken>
	'authorization'	  = "Bearer <AccessToken>"
    'x-domain-name'   = <email-domain-name>
}

The x-domain-name header is only required when using a tenant-level account (ie. an account that is associated with a single tenant). This should match the email domain of the user account associated with the token.

The new access/refresh token will be returned in JSON format. Future API calls will have to pass these values in the aforementioned authorization header.