OpenID Connect

Configure OpenID Connect with Universal.

OpenID Connect requires a license.

OpenID Connect is an authentication layer on top of OAuth 2.0, an authorization framework. It is supported by many vendors and provides the ability to authenticate against systems like AzureAD.

This document will outline the steps necessary to configure AzureAD OpenID Connect and use it with Universal.

Configuring Azure Active Directory

Within the Azure Portal, navigate to your Azure Active Directory blade. Next, click the App registrations node and then click New registration.

In the New registration page, enter the name of your application and the reply URL. The URL can be configured in the appsettings.json for Universal but the default value is shown below.

Next, you'll need to configure a client secret. You can click the Certificates & secrets menu and then click New client secret. This secret will need to go into the appsettings.json file.

Now, you will need to take note of your Application (client) ID GUID. This will be used in the appsettings.json file.

Finally, you will have to click the Endpoints button to open the Endpoints drawer. This contains a list of the endpoints. Make note of the OAuth 2.0 authorization endpoint URL. You will need this for the appsettings.json.

Note that you will not input the entire endpoint URL. You will need to include the portion of the URL through the GUID but without the path after oauth2 in the Authority setting below (e.g. https://login.microsoftonline.com/fffffff-4b76-4470-a736-8481d7a2ed87).

Configuring Universal for Azure Active Directory

Use Appsettings.json

Read more about appsettings.json on our Settings page.

Now that we have completed the configuration of an AzureAD App Registration, we can update the appsettings.json file with the appropriate settings. For my application, it would look something like this.

    "OIDC": {
      "Enabled": "true",
      "CallbackPath": "/auth/signin-oidc",
      "ClientID": "6f006906-643a-40fe-af00-9060ceffffff",
      "ClientSecret": "xxxxxxxxxxxxxxxxxx",
      "Resource": "",
      "Authority": "https://login.microsoftonline.com/fffffff-4b76-4470-a736-8481d7a2ed87",
      "ResponseType": "code",
      "SaveTokens": "false",
      "GetUserInfo": false
    },

If you are using Chrome, you will also need to enable HTTPS. You will see a 500 error without HTTPS enabled.

Use Authentication.ps1

Available in PowerShell Universal 2.5 or later.

You can use the admin console to configure OpenID Connect. We recommend this method as you will not need to restart the PowerShell Universal service after configuring OIDC.

To add a new authentication method, navigate to Security \ Authentication and add the OpenID Connect provider.

Once the provider has been added, you can click the details button to enter the settings you'll need to authenticate against your OIDC provider. After setting the OIDC options, set the provider to enabled and log out. When visiting the /admin page, you'll be prompted for OIDC login.

Delegated Access Tokens

You can use access tokens generated by an OIDC login for other services the user may have access to. Within your OIDC provider, like Azure AD, you can grant additional permissions to the token.

You will also have to enable access tokens within the authentication flow so that the token provides the necessary resource access.

Finally, within your PSU appsettings.json file, you will need to ensure that SaveTokens is enabled, the resource type includes token and the resource you wish to access is included in the Resource setting. The URL that you specify in the resource should be listed in within the provider.

The below example adds a resource for Microsoft O365.

    "OIDC": {
  "Enabled": "true",
  "CallbackPath": "/auth/signin-oidc",
  "ClientID": "<clientID>",
  "ClientSecret": "<clientSecret>",
  "Resource": "https://manage.office.com/",
  "Authority": "https://login.microsoftonline.com/tenant",
  "ResponseType": "id_token token",
  "SaveTokens": "true",
  "UseTokenLifetime": true
},

Within your dashboard, you will now have access to an $AccessToken and $IdToken variable that you can use with cmdlets that require authorization.

For example, the Connect-AzureAd cmdlet accepts an access token.

Connect-AzureAD
       [-AzureEnvironmentName <EnvironmentName>]
       [-TenantId <String>]
       -AadAccessToken <String>
       [-MsAccessToken <String>]
       -AccountId <String>
       [-LogLevel <LogLevel>]
       [-LogFilePath <String>]
       [-InformationAction <ActionPreference>]
       [-InformationVariable <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Configuring Okta

Okta supports OpenID Connect. You can configure an application to allow authentication against PowerShell Universal instances.

Within your Okta admin console, expand Applications and click Applications. Then click Create App Integration.

Select OIDC and Web Application.

Name your application and define the Sign-In redirect URL used to call your PowerShell Universal server. You will need to specify this callback URL within your PowerShell Universal configuration.

Once you've created your application, take note of your Client ID and Client Secret. You will specify these within your PowerShell Universal configuration.

Within the Sign On tab, specify the group claims filter to use for providing claims to PowerShell Universal. These claims can be used to assign roles based on group membership. The following filter returns all claims.

Once you have your Application configured, you can configure PowerShell Universal.

Configurating Universal for Okta

Once you have defined your Okta application, you can set your appsettings.json file to use the provider for logins. Below is an example of the section required for Okta to function. Take note of the scope functionality as it is required for retrieving group membership.

    "OIDC": {
      "Enabled": "true",
      "CallbackPath": "/authorization-code/callback",
      "ClientID": "6f006906-643a-40fe-af00-9060cea5d6ef",
      "ClientSecret": "M~.rE56.md_MOpB2I5kwj_voFuX-i891N0",
      "Resource": "",
      "Authority": "https://poshtools.okta.com",
      "ResponseType": "code",
      "SaveTokens": "true",
      "CorrelationCookieSameSite": "",
      "UseTokenLifetime": true,
      "Scope": "openid profile groups",
      "GetUserInfo": true
    },

Role-Based Access

In order to look up group membership for Okta, you will need to use the $UserInfo variable that is available within roles.ps1. This variable provides additional information about the user logging in.

The groups property will contain a list of groups the user is a member of. You can validate membership by checking whether the list contains the desired group.

param($User)

$UserInfo.groups -contains 'Administrators'

Delegated Access Tokens

Access tokens are available for users within their scripts. You can use access tokens in jobs started by users and dashboards.

For example, you could return the current user's information by using the access token provided by Okta.

Invoke-RestMethod https://poshtools.okta.com/oauth2/v1/userinfo -Headers @{
    Authorization = "Bearer $AccessToken"
}