User Management with an External Identity Provider

This topic describes how to configure IDCS as an external OpenID Connect (OIDC) identity provider for Oracle Blockchain Platform Enterprise Edition.

Prerequisites

Before creating an instance in Oracle Blockchain Platform Enterprise Edition:

• Create an administrator account in the selected identity provider.
• Create users and groups required for Oracle Blockchain Platform Enterprise Edition administration and blockchain access.
• Register a confidential OIDC client application.
• Obtain the client ID, client secret, issuer, authorization, token, JWKS, and revocation endpoints.
• Determine the claim names used for the username, client ID, and group memberships.

Configure IDCS

Configure the confidential client

1. Sign in to the IDCS identity domain. Create a domain.
2. Create a confidential client application for the Oracle Blockchain Platform Enterprise Edition control plane.
   1. Navigate to Profile , and then Identity Domain, and then Integrated applications.
   2. Select Add application button, and then Confidential Application, and then Launch Workflow and provide a name before submitting to create the confidential application.
   3. After the application is created, select the application and navigate to the OAuth configuration tab. Select Edit OAuth configuration.
   4. Select these options for Resource Server Configuration:
      • Configure this application as a resource server now
      • Allow token refresh
      • Primary Audience: obpee-cp
   5. Select these options for Client Configuration:
      • Configure this application as a client now
      • For Allowed grant types, select
        • Resource owner
        • Refresh token
        • Authorization code
      • Client type: Confidential
   6. Certificate:
      • Select Bypass consent
      • Client IP address: Anywhere
   7. Token issuance policy:
      • Authorized resources: All
3. Create groups and users in the domain. Navigate to Profile , and then Identity Domain, and then User management.

   See User Groups and Roles for details about the groups and how they're used.

4. Configure the required redirect URI for the Oracle Blockchain Platform Enterprise Edition control plane and service console.
5. Assign the users and groups to the confidential client application. Navigate to Confidential Application, and then Users and Confidential Application, and then Groups to do this.

Configure group claims

To include group memberships in access tokens:

1. Open the OAuth configuration for the confidential client.
2. Add the Identity Domain Administrator application role.
3. Use an administrator account to obtain an access token through the token endpoint. The administrator must belong to the IDCS_Administrators and, where applicable, OCI_Administrators groups.
4. Use the access token to create a custom access-token claim.

curl -sS -X POST "https://<identity-domain-host>/admin/v1/CustomClaims" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "schemas": ["urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"],
    "name": "group_roles",
    "value": "$user.groups.*.display",
    "expression": true,
    "mode": "always",
    "tokenType": "AT",
    "allScopes": true
  }'

Use group_roles as the Groups Claim Name in the Oracle Blockchain Platform Enterprise Edition configuration.

Configure Oracle Blockchain Platform Enterprise Edition

Enter the identity provider values in the Oracle Blockchain Platform Enterprise Edition external OIDC provider configuration.

1. Open Blockchain Platform Manager at https://controlplane.domainname/console/index.html. Your browser might warn you about a self-signed certificate.
2. Log in to Blockchain Platform Manager by using the obpadmin username and the password that you provided during installation.
3. On the Configuration page, select Authentication Servers.
4. Select Add Identity Provider
5. Complete the following configuration fields on the Add Identity Provider page:

   Field	Required	Description
   Well-known configuration URI	Yes	OIDC discovery URL for the identity provider. This is Domain URL/.well-known/openid-configuration The Domain URL can be found in Identity and Security, and then Identity, and then Domains, and then Domain URL
   Issuer URL	No	Issuer used to validate token origin.
   JWKS URL	No	Endpoint used to validate token signatures.
   Authorization endpoint	No	Endpoint used for browser-based authentication.
   Token endpoint	No	Endpoint used to exchange the authorization code for tokens.
   Revocation endpoint	No	Endpoint used to revoke refresh tokens.
   Scope	Yes	OIDC scopes, for example openid email profile offline_access.
   Client claim name	Yes	Claim containing the client identifier, such as cid or azp.
   Client claim value	Yes	Expected value of the client identifier claim.
   Client ID	Yes	Confidential client identifier.
   Client secret	Yes	Confidential client secret.
   User claim name	Yes	User identifier claim, such as preferred_username or email.
   Blockchain Platform Manager (BPM) Admins	Yes	Provider group mapped to Blockchain Platform Manager administrators.
   Groups claim name	Yes	Claim containing group memberships, such as groups or group_roles.

6. Complete the group name fields as required. These can be found here: Groups
7. Once all fields are populated, click Save and Set Active.

Ensure Domain Settings have Configure Client Access Enabled

Ensure that the domain settings have Configure Client Access enabled. To verify or enable this:

1. Access the IDCS console at:

   <Domain-URL>/ui/v1/adminconsole

2. Sign in with a user that has the Identity Domain Administrator role (or equivalent tenant/domain admin permission).
3. Navigate to Settings tab, and then Domain settings - Access signing certificate and ensure that Configure client access is enabled.
4. If it is disabled, enable it using Edit domain settings.

Add a Redirect URL for Blockchain Platform Manager

After logging out of Blockchain Platform Manager, when you attempt to log back in it will go through your new identity provider. This requires that you add a redirect URL.

For example, if you are using IDCS, complete the following steps:

1. Log in to OCI and go to Identity and Security.
2. Select Integrated Applications.
3. Select the confidential application you created.
4. Select OAuth Configuration, and click Edit OAuth Configuration.
5. Add a redirect URL to the list with the URL for your Blockchain Platform Manager URL. Click Submit.

Note:

• After you create your instance, you will need to add another redirect for your Blockchain Platform console URL. It is instance-specific and cannot be added until after the instance is created.
• If you deploy a sample application, you will need to add another redirect for the sample application URL.