# OAuth 2.0 and OpenID Connect

> Provides an overview of the OAuth 2.0 and OpenID Connect protocols, explaining their roles in authentication and authorization processes within ReversingLabs products.

# Configure OAuth 2.0 and OpenID Connect SSO

OpenID Connect (OIDC) enables single sign-on authentication for [Spectra Analyze](/SpectraAnalyze/) and [Spectra Detect](/SpectraDetect/) Manager using your organization's identity provider. This guide covers client configuration, claim mapping, signature verification, and user access control for OIDC integration with providers like Okta, Azure AD, and ADFS.

For SAML-based SSO, see [SAML Configuration](/General/SecurityAndAccessControl/SAML). For privacy and data handling policies, see [Privacy](/General/SecurityAndAccessControl/Privacy).

## Configuration steps

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**

![](images/openid-appliance-client.png)

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 `aud` value 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 `iss` value 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.

![](images/openid-appliance-provider.png)

**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.

![](images/openid-appliance-signature.png)

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. If using multiple groups, a user must be present in at least one group to be granted 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. If using multiple groups, a user must be present in all groups configured to be granted access.

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.

**Note: 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                    | Short name of the claim containing the unique username for identifying the user. Usernames are case-insensitive. For example, "john" and "John" cannot coexist. |
| E-mail                      | 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                  | (Optional) 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. |
