ENTERPRISE  This is an EJBCA Enterprise feature.

The following provides workflows and instructions for managing OAuth providers in EJBCA.

For more conceptual information about OAuth providers, see OAuth Providers Overview.

Prerequisites

Since OAuth authentication works by redirecting the user to the external provider, and then back to EJBCA, the externally visible hostname (and HTTPS port) must be set correctly. This can be configured in conf/web.properties, with the properties httpsserver.hostname and httpserver.pubhttps. For more information about the properties, see Managing EJBCA Configurations.

Configuring OAuth Providers in the CA UI

OAuth Providers are configured on the System Configuration Trusted OAuth Providers tab (CA UI → System Configuration → Trusted OAuth Providers).

The Trusted OAuth Providers tab shows a list of currently configured providers. The UI also provides functionality to add, edit, and remove OAuth Providers as well as set a default trusted provider. Note that only administrators who are granted root access are permitted to view and access the Trusted OAuth Providers tab.

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.

Configuring OAuth Providers in the Command Line Interface

OAuth Providers can also be configured using the command line ejbca.sh script. The script is located in the bin folder of the EJBCA installation source, see Local Command Line Interface (EJBCA CLI) for more information.

To configure Trusted OAuth Providers using the ejbca.sh command line, do the following:

Run the following command to display available subcategories for the config command:

./ejbca.sh config
BASH

The output lists available subcategories, including oauth:

The following subcategories are available for the command 'config':
    [ cmp | est | oauth | protocols | scep ]
--------------------------------
And the following commands are available:
    dump        Shows the current server configuration

Type a command and "--help" for more information.
BASH

Next, issue the oauth subcommand to list all available options:

bin/ejbca.sh config oauth
--------------------------------
The following commands are available:
    addoauthprovider            Adds a new Trusted OAuth Provider to the list of available providers.
    editoauthprovider           Edit key identifier, public key and/or skew limit for an existing Trusted OAuth Provider.
    listoauthproviders          Lists the current oauth providers available in EJBCA
    oauthproviderkey            Adds or removes public key of Trusted OAuth Provider with defined label.
    removeoauthprovider         Remove an existing Trusted OAuth Provider from the list of keys.
    setdefaultoauthprovider     Sets one of the existing Trusted OAuth Providers as default.
    viewoauthprovider           Displays information about the specified Trusted OAuth Provider available in EJBCA

Type a command and "--help" for more information.
BASH

The commands listed can be used for adding, editing, and listing existing OAuth providers, as well as removing or setting a default OAuth provider.

The following describes how to add and edit a Trusted OAuth Provider using the command line. For more information on using the other oauth commands, run oauth --help.

Adding a Trusted OAuth Provider

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

ejbca.sh config oauth addoauthprovider --help
BASH

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.

    Mandatory parameters:
        --audience <AUDIENCE> (Switch is not required)
            Expected value in token's 'aud' claim.
        --label <PROVIDER_NAME> (Switch is not required)
            Trusted OAuth Provider name.
        --skewlimit <SKEW_LIMIT> (Switch is not required)
            Skew limit to be used.
        --type <PROVIDER_TYPE.> (Switch is not required)
            Type of the Trusted OAuth Provider. Supported types are GENERIC, PINGID, KEYCLOAK and
            AZURE.

    Optional parameters:
        --client <CLIENT_NAME> (Switch is not required)
            Client name for EJBCA in Trusted OAuth Provider.
        --clientsecret <CLIENT_SECRET> (Switch is not required)
            Client secret in Trusted OAuth Provider.
        --clipassword <CLI_PASSWORD>
            Set the CLI user's password explicitly on the command line with
            --clipassword=<password>
        --logouturl <PROVIDER_LOGOUT_URL> (Switch is not required)
            Trusted OAuth Provider logout endpoint URL.
        --realm <REALM/TENANT_NAME> (Switch is not required)
            Trusted OAuth Provider realm name.
        --scope <SCOPE> (Switch is not required)
            Trusted OAuth Provider scope. Used for Azure Trusted OAuth Providers.
        --tokenurl <PROVIDER_TOKEN_URL> (Switch is not required)
            Trusted OAuth Provider token endpoint URL.
        --url <PROVIDER_URL> (Switch is not required)
            Trusted OAuth Provider authorization endpoint URL.
BASH

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:

Trusted OAuth Provider with the same label already exists!
TEXT

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

The Skew Limit is the value (in milliseconds) used to allow for a minor time difference (usually less than 10 minutes) between the systems (e.g EJBCA and OAuth Provider)

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

bin/ejbca.sh config oauth addoauthprovider --label testlabel --skewlimit 50000 --type keycloak --url testurl --client testclient --realm testrealm --audience audience
BASH

The following shows the successful output of the above command:

Trusted OAuth Provider with label testlabel added successfully!
TEXT

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:

Trusted OAuth Provider with same kid or internal Id exists!
TEXT

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

The Skew Limit is the value (in milliseconds) used to allow for a minor time difference (usually less than 10 minutes) between the systems (e.g EJBCA and OAuth Provider).

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

bin/ejbca.sh config oauth addoauthprovider --keyidentifier test --publickey pubkey.pem --skewlimit 1500 --audience audience
CODE

The following shows the successful output of the above command:

Trusted OAuth Provider with kid: test added successfully!
CODE

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

bin/ejbca.sh config oauth listoauthproviders
BASH

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

Kid: test | skew limit: 1500 | publickey fingerprint: mb93lXyccgohbB2ze4x2zXHr5ep84MCZvcqHM0HN0Ts=
TEXT

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:

bin/ejbca.sh config oauth oauthproviderkey --label testlabel --action add --keymethod file --keyfile public.pem --keyidentifier testkeyid
BASH

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

Public key successfuly added to Trusted OAuth Provider with label testlabel!
TEXT

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:

bin/ejbca.sh config oauth viewoauthprovider --label test
BASH

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):

bin/ejbca.sh config oauth editoauthprovider --keyidentifier test --help
BASH

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

    Mandatory parameters:
        --label <LABEL> (Switch is not required)
            Label of the Trusted OAuth Provider to update its parameters.

    Optional parameters:
        --new-client <CLIENT_NAME> (Switch is not required)
            Updated Client Name.
        --new-audience <AUDIENCE> (Switch is not required)
            New Audience.
        --new-clientsecret <CLIENT_SECRET> (Switch is not required)
            Updated Client Secret.
        --new-label <PROVIDER_NAME> (Switch is not required)
            Updated Provider Label.
        --new-logouturl <PROVIDER_LOGOUT_URL> (Switch is not required)
            New logout endpoint URL.
        --new-realm <REALM/TENANT_NAME> (Switch is not required)
            Updated Realm/Tenant name.
        --new-scope <SCOPE> (Switch is not required)
            Updated Scope.
        --new-skewlimit <SKEW_LIMIT> (Switch is not required)
            Updated Skew Limit.
        --new-tokenurl <PROVIDER_TOKEN_URL> (Switch is not required)
            New token endpoint URL.
        --new-url <PROVIDER_URL> (Switch is not required)
            Updated URL to the login page.
TEXT

Related Content