Adding a Trusted OAuth Provider

To add a new OAuth Provider:

1. Select System Configuration → Trusted OAuth Providers.

2. Click Add at the bottom of the page to view the Add Trusted OAuth Provider page with mandatory and optional fields of the provider.

3. Specify the fields according to the following:

   • OAuth Provider Type: Choose the type of the provider. Currently supported types are Generic, Azure, PingID and Keycloak.

   • OAuth Provider Name: Specify a unique label for the provider. Mandatory for all providers.

   • URL: Set the base login URL for the provider. For Azure, this could be https://login.microsoftonline.com. For local testing with Keycloak, this can be configured as http://localhost:8084/auth. This field does not appear for Ping ID.
     

   • Authorization URL: Set the Authorization endpoint URL for the provider. For Ping ID, the value for this field can be found in the Configuration tab of your application (under Connections / Applications).
     

   • Token URL: Set the Token endpoint URL for the provider. For Ping ID, the value for this field can be found in the Configuration tab of your application (under Connections / Applications).
     

   • Logout URL: Set the Logout endpoint URL for the provider. For Ping ID, the value for this field can be found in the Configuration tab of your application (under Connections / Applications).
     

   • Skew Limit (ms): Set a Skew limit in milliseconds. The Skew Limit defaults to 1 minute but can be set to an arbitrary non-negative integer.

   • Audience: Set the expected audience value. Audience must be equal to the aud value in the JSON token from this provider. This value identifies that the login token is intended for use by EJBCA. For more information on the purpose of an Audience claim and how to set it, see Configuring Audience Claims.
     

   • Disable Audience Check: Select to support OAuth providers that do not support Audience claims, like PingID. Disabling this check has security implications and is not recommended, see Configuring Audience Claims for more information.

   • Client Name: Specify the Client field. Mandatory for Azure, Ping ID, and Keycloak.

   • Client Secret: Enter the Client Secret. Mandatory for Azure and Ping ID providers.

   • Public Key input method: Choose how the Public Key will be provided. The options are File Upload, Text Value and Configuration URL.

   • OAuth Key Identifier: Specify an OAuth Key Identifier using any arbitrary string. The OAuth Key Identifier must be unique and cannot use the same identifier as any Public Key of this or any other existing provider. OAuth Key Identifier must be equal to the kid value in the JSON token from this provider.

   • Upload Public Key: Adds the Public Key to the provider. More than one key can be added if necessary. Every provider should have at least one public key to function properly.
     
     

4. Click Add to add the Trusted OAuth Provider.

In addition to the above fields, there are also some fields exclusive to certain provider types.

Azure providers have the following extra fields:

• Tenant: Specify the tenant for the provider.

• Scope: Set the scope. In the Azure Active Directory, this can be configured in Expose an API → Add a scope.

Keycloak providers have the extra field:

• Realm: Enter the realm name. This corresponds to the configured Keycloak Realm.

The Trusted OAuth Providers tab displays all existing providers, listed with their name and URL. The View button next to a provider opens a more detailed view of the fields of the provider.

Editing a Trusted OAuth Provider

The Edit button allows the administrator to edit all configuration fields. Like with adding a new provider, the UI will not allow duplicate Key Identifiers. To remove a provider, click Remove.

The Default Trusted OAuth Provider option allows you to set a default provider. By default, no provider is set as default.

Adding a Trusted OAuth Provider

To list all available mandatory parameters for the addoauthprovider command, run the following:

This outputs a listing of mandatory parameters and optional parameters for the addoauthprovider command. Please note that depending on the provider type, some of the parameters listed as optional may be required.

The type parameter determines whether the configured provider is of unspecified (generic), Keycloak, Ping ID, or Azure type. Different types of providers have different required fields. If a type-specific required parameter is not specified the command output will contain an error specifying which parameter is missing.

For Azure providers, the type-specific mandatory parameters are Provider URL (--url), Tenant (--realm), Scope (--scope), Client Name (--client) and Client Secret (--clientsecret). Please note that the encryption key to encrypt the client secret for storage should be provided in cesecore.properties as password.encryption.key as relying on the default key is not secure.

For Keycloak providers, the type-specific mandatory parameters are Provider URL (--url), Realm (–realm) and Client Name(–client).

For Ping ID providers, the type-specific mandatory parameters are the Authorization URL (--url), Token URL (–tokenurl), Logout URL (–logouturl), Client Name(–client) and Client Secret (--clientsecret).

The label of the provider must be unique. If the label is not unique, an error is displayed:

The skewlimit format must have a non-negative integer value.

To add an OAuth provider, run the addoauthprovider command according to the following example:

The following shows the successful output of the above command:

The keyidentifier parameter is a unique ID used as the external ID shown in the CLI and GUI for the added provider.

The ID must be unique and if attempting to use an already existing ID, you will get an error similar to the following:

The skewlimit format must have a non-negative integer value.

To add an OAuth provider, run the addoauthprovider command according to the following example:

The following shows the successful output of the above command:

Once you have added the provider, run the following to list available providers:

The output shows the provider with keyidentifier test and skewlimit set to 1500 milliseconds:

Add Public Key(s) to a Trusted OAuth Provider

A configured provider will need a public key to be functional. The oauthproviderkey command is used to add a public key to an existing provider. The label (--label) parameter is mandatory and determines the provider to be operated on. More than one can be added if necessary and public keys can also be removed (use --action remove).

When adding a key, the keymethod parameter has to be set. It is possible to add the public key either from a file (--keymethod file), from text (--keymethod text) or by providing a configuration URL (--keymethod url). The public key file, text and configuration URL can be specified by the parameters --keyfile, --key and --keyurl respectively.

Key files must contain a public key in PEM, DER or JWK format, or an X.509 certificate in PEM or DER format. When keys are provided as text, they must either use PEM, DER or JWK format, or be Base64 encoded.

A key identifier is also needed for the public key. Key identifiers should be unique across all public keys of all Trusted OAuth Providers. If a duplicate would be added an error is shown instead.

The following shows an example command:

Successful execution of the command is confirmed by the following output:

Viewing a Trusted OAuth Provider

The viewoauthprovider command is used for viewing detailed information about a single provider (for an overview of all providers see listoauthproviders instead). All fields of the provider except for the Client Secret field are displayed.

The command can be used as follows:

Editing a Trusted OAuth Provider

The editoauthprovider command is used for editing an existing trust provider.

Run the following to list the parameters of the editoauthprovider command for the given provider (test):

The output lists and explains the mandatory and optional parameters of the command.

Related Content

• Page:Setting up OAuth Using Azure Active Directory

• Page:Integrating EJBCA with Azure AD Role Based Authentication (RBAC)

• Page:Setting up OAuth Using Keycloak

• Page:OAuth Providers