OAuth 2.0 / OpenID Connect
To configure OpenID Connect on the Spectra Analyze or Spectra Detect Manager appliances, go to the appropriate dialog:
- For Spectra Analyze, navigate to Administration > Configuration > Authentication
- For Spectra Detect Manager, navigate to Administration > Spectra Detect Manager > Authentication
In the dialog, select the OAuth 2.0/OpenID Connect option. This will expand the dialog and display additional configuration options divided into sections - OpenID Connect client, OpenID Connect provider, Signature verification, Claim mapping, User access, Miscellaneous.
1.1 OpenID Connect client
Find the Client Identifier value previously copied and saved, and enter it into the Client ID field.
Select the type of client (public or confidential). If confidential is selected, find the Secret value previously copied and saved, and enter it into the Client secret field.
Configure the remaining options:
- Check Verify SSL certificate if the OIDC client needs to verify the SSL certificate of the authorization server
- Fill the Config URL field if you have previously configured an OpenID Connect discovery document (using the .well-known/openid-configuration endpoint)
- Select the source from which claims about the user will be taken:
- ID Token
- UserInfo endpoint
- Access Token
If Access Token is selected, additional options are available:
- Audience: Identifies the intended recipient of the token. This corresponds to the
audvalue in the token. - Relying Party ID/Resource: The ID of the application requesting user authentication from the Identity Provider. In this case, it should be set to the identifier assigned to the appliance in the Identity Provider's configuration.
- Issuer: Corresponds to the
issvalue in the token.
Finally, check Enable PKCE in case your authentication provider requires PKCE as additional verification.
1.2 OpenID Connect provider
If the Config URL field was used in the previous step, these fields will already be configured. If you need to enter them manually, examples are below. The Scopes field needs to be validated manually.
Example values
Authorization Endpoint: https://auth.example.com/adfs/oauth2/authorize/
Token Endpoint: https://auth.example.com/adfs/oauth2/token/
UserInfo Endpoint: https://auth.example.com/userinfo
Values listed in the Scopes field refer to the OpenID Connect scopes that will be requested during login. The allatclaims scope should be included to allow access to the claims if using the customized ID Token.
Enter the desired values into the Scopes field. An example using Okta would look like this: openid profile email groups.
1.3 Signature verification
In the Signature algorithm pull-down menu, select the algorithm used to sign the ID token. Supported options are RS256 and HS256.
If RS256 is selected as the algorithm, the Signature public key or the JWKS Endpoint must also be configured.
If the JWKS Endpoint has to be used, its URL can be found in the openid-configuration metadata document as the value assigned to the jwks_uri parameter. This URL should then be entered into the JWKS Endpoint field in the dialog.
1.4 Claim mapping
This section allows mapping OpenID Connect claims to internal user attributes on the appliance.
ID Token or Access Token must be selected in the OpenID Connect client section to retrieve additional claims from customized tokens.
The short name of each claim should be entered into the corresponding field. In the Username field, it is possible to enter unique_name to use the unique name claim; email to use the email address claim; or any other short name to use a particular claim.
Username and Email are mandatory fields, you could use email for both. The First Name, Last name, and Group fields are optional. It is highly recommended to use groups which determine the right level of access for users defined in the User Access section next.
The Claim Mapping Groups Delimiter field should only be used if your IDP sends all groups as one long string of characters with a delimiter. (Not common)
1.5 User access
All fields in this section are optional. Each field accepts only one value (the name of just one group). If a field is left blank, it will be ignored (treated as if it is not configured).
The IDP must be configured to send groups as part of the scopes configured above in order to correctly use the group values in this section.
The Active flag group field accepts the name of the group containing active users. If a user is not in this group, they will be marked as inactive and denied access.
The Superuser flag group field accepts the name of the group containing superusers (administrators). Users will be marked as superusers only if they are in this group.
The Require group field accepts the name of the group containing users who have access to the appliance. Authentication will fail for every user that is not in this group.
The Deny group field accepts the name of the group containing users who are not allowed to access the appliance. Authentication will fail for every user that is in this group.
The Active and Require groups function similarly, but only one should be used at a time. Superusers must belong to both the Superuser flag group and either the Active or Require group (whichever group is chosen is also used to determine the full list of users.)
1.6 Miscellaneous
This section can be used to require the authorization server to always re-authenticate the user, even if the user is already authenticated.
To enable this option, select the “Always prompt for login” checkbox.
Configuration reference
Administration > Configuration > Authentication > User Directory: OAuth 2.0/OpenID Connect
| OpenID Connect client | |
|---|---|
| Client ID | Client Identifier value for the application. This should be provided to the appliance administrator by the OpenID Connect provider. |
| Client Type | Specifies if the appliance will be configured as a public or a confidential application. Possible values are Public (do not use Client Secret) and Confidential (use Client Secret). If set to Confidential, the Client secret must be provided in the next field. |
| Client secret | Visible only if Client Type is set to Confidential (use Client Secret). The value used by the application to authenticate to the authorization server. This should be provided to the appliance administrator by the OpenID Connect provider. |
| Verify SSL certificate | If this checkbox is selected, the OpenID Connect client will verify the SSL certificate of the provider responses. |
| Config URL | Can be optionally used to populate configuration fields by providing the URI discovery mechanism URL of the Identity Provider and clicking the Get button. |
| Claim Source | Specifies which source will be used to authenticate and authorize users. Supported values are Use ID Token (OpenID), Use UserInfo endpoint (OpenID) and Use Access Token. |
| Audience | Visible only if Claim Source is set to Use Access Token. Specifies the expected value of the Audience (aud) field in the token to confirm its validity. |
| Relying Party ID/Resource | Visible only if Claim Source is set to Use Access Token. The ID of the application requesting user authentication from the Identity Provider. In this case, it should be set to the identifier assigned to the appliance in the Identity Provider's configuration. |
| Issuer | Visible only if Claim Source is set to Use Access Token. Specifies the expected value of the Issuer (iss) field in the token to confirm its validity. |
| Enable PKCE | Additional verification method used by some identity providers. The code challenge method used by the Spectra appliance is always S256. |
| OpenID Connect provider | |
| Authorization Endpoint | URL of the OpenID Connect provider authorization endpoint. This endpoint handles authentication and authorization of users. |
| Token Endpoint | URL of the OpenID Connect provider token endpoint. This endpoint can be used by a client application to request and obtain ID, refresh, and access tokens. |
| UserInfo endpoint | Visible only if Claim Source is set to Use UserInfo endpoint (OpenID). URL of the OpenID Connect provider UserInfo endpoint. The UserInfo endpoint is a protected resource from which client applications can retrieve information about claims for the logged-in user. |
| Scopes | Provide one or more scopes that should be requested during login. |
| Signature verification | |
| Signature algorithm | Select which algorithm should be used to sign ID tokens. Supported options are RS265 and HS256. If RS256 is selected as the algorithm, the Signature public key or the JWKS Endpoint must also be configured. |
| Signature public key | The key used to sign ID tokens when using the RS256 signature algorithm. |
| JWKS Endpoint | URL of the JWKS (JSON Web Key Set) endpoint configured by the OpenID Connect provider. |
| Claim mapping | |
| Username | (Optional) Short name of the claim containing the unique username for identifying the user. Usernames are case-insensitive. For example, "john" and "John" cannot coexist. |
| Short name of the claim containing the email address of the user. The address itself doesn't have to be unique - multiple users can have the same email. | |
| First name | Short name of the claim containing the first name of the user. |
| Last name | (Optional) Short name of the claim containing the last name of the user. |
| Groups | (Optional) Name of the claim that contains a list of user groups. |
| Groups Delimiter | (Optional) Character to split the Groups string on. |
| User access | |
| Active flag group | Accepts names of one or more groups containing active users. If a user is not in one of these groups, they will be marked as inactive and denied access. |
| Superuser flag group | Accepts names of one or more groups containing superusers (administrators). Users will be marked as superusers only if they are in one of these groups. |
| Require group | Accepts names of one or more groups containing users who have access to the appliance. Authentication will fail for every user that is not in one of these groups. |
| Deny group | Accepts names of one or more groups containing users who are not allowed to access the appliance. Authentication will fail for every user that is in one of these groups. |
| Access Groups Delimiter | Character to split the User Access Groups on. Characters entered in this field must not be used in any access group name. Max length of delimiter is 2 characters. |
| Miscellaneous | |
| Always prompt for login | Select the checkbox to require the authorization server to always re-authenticate the user, even if the user is already authenticated. If this option is enabled, the prompt=login parameter will be added to the authentication query. This option should not be used as a security measure, because the parameter can be removed by users to bypass re-authentication. |