Using external bearer (JWT) tokens with PowerShell Universal

Discuss this Article

PowerShell Universal uses JSON Web Tokens to allow for access to APIs within the system. It makes it easy to issue app tokens and control them directly within the platform. That said, JWT is a standard technology, and you may want to use tokens issued by other authorization servers. In this post, we’ll look at how to use Okta tokens with PowerShell Universal.

Configuring Okta

First, we’ll need to register an app within Okta so we can grant tokens. This is the same process you would use to setup OpenID Connect authentication. Create an Okta app for OIDC and set as a Web Application.

Ensure that you select Refresh and Implicit (hybrid) as the grant types. You can change these settings after the app has been created.

On the Sign On tab, configure the OpenID Connect Token settings to include all groups. You can filter this however you like but you will need to do so in order to provide the proper claims to PowerShell Universal.

Take note of the audience in the above settings. This is the audience that PowerShell Universal will use to validate the token. Now that we have our app created and configured, we can setup PowerShell Universal to use the tokens.

Configuring PowerShell Universal

Within the appsettings.json file, you will need to add the following settings to configure PowerShell Universal to use the Okta tokens. The issuer is the URL of your Okta tenant. The audience is the audience you retrieved in the Okta app. The discovery document is the URL to the OpenID Connect configuration for your Okta tenant. The RoleClaimType is the claim that contains the roles that the user has. In Okta, this claim type is groups. This will allow PowerShell Universal to use the roles to determine access to APIs and endpoints. Note that this setting is new and will be included in v4.2.21 and later.

"Jwt": {
    "Issuer": "https://dev-36706648.okta.com",
    "Audience": "0oaf9z1slgkZ7twIn5d7",
    "DiscoveryDocument": "https://dev-36706648.okta.com/.well-known/openid-configuration",
    "RoleClaimType": "groups"
}

With these settings in place, PowerShell Universal will now use the Okta tokens to authenticate users and authorize access to APIs and endpoints. PowerShell Universal does not run role policies nor use claim to role mapping on JWT tokens so you will need to ensure that the roles are properly configured within Okta.

Pulling a Token and using it in PowerShell Universal

With all the systems configured, you can now pull tokens from Okta and use them to access PowerShell Universal. An easy way to do this is with a tool like Postman. First, you need to authenticate your user account to receive a session token. Create a new request to the Okta /authn endpoint in your Okta tenant. You need to include your username and password as a JSON value in the body of the request.

If successful, your session token will be listed in the response. Next, make a request to the /authorize endpoint. You will need to include all of the query string values that are listed below.

• client_id - The client ID of your Okta app
• response_type - The response type. This should be id_token
• response_mode - The response mode. This should be form_post. This ensures an HTML document is returned that you can read.
• redirect_uri - The redirect URI of your Okta app. This needs to be the same as the one you configured in your Okta app. It doesn’t need to be a real URL.
• sessionToken - The session token you received from the /authn endpoint.
• scope - The scope of the request. This should be openid groups.
• state - A random string that you generate.
• nonce - A random string that you generate.

Send the request. If the request fails, an error message will be present in the document. If it is successful, you’ll see a bearer token.

You can now use this token to access PowerShell Universal. You can use this token in the Authorization header of your requests.

$headers = @{ 
    Authorization = "Bearer $token"
}
Invoke-RestMethod http://localhost:5000/api/v1/role -Headers $headers