4 Set Up Users and Access Roles

One of the first jobs you do after setting up a service with Oracle Blockchain Platform is to add user accounts in Oracle Identity Cloud Service for everyone you expect to use the service and assign them suitable permissions in the service.

Oracle Identity Cloud Service is available with your Oracle Blockchain Platform account. Use Oracle Identity Cloud Service to add users and groups.

Use Oracle Identity Cloud Service for Authentication

Oracle Blockchain Platform uses Oracle Identity Cloud Service for identity management and authentication.

Oracle Identity Cloud Service provides Oracle Cloud administrators with a central security platform to manage the relationships that your users have with your applications, including with other Oracle Cloud services like Oracle Blockchain Platform. With Oracle Identity Cloud Service you can create custom password policies and email notifications, onboard new users, assign users and groups to applications, and run security reports. See these topics in Administering Oracle Identity Cloud Service:

Each Oracle Cloud service instance in your account is associated with an Oracle Identity Cloud Service security application. Each security application defines one or more application roles. Assign users and groups to these application roles in order to grant them administrative access to a service. See these topics in Administering Oracle Identity Cloud Service:

Connect to Oracle Identity Cloud Service from the Cloud Infrastructure Console

When you create an Oracle Blockchain Platform instance, Oracle Cloud creates a security application for the instance in Oracle Identity Cloud Service Oracle Identity Cloud Service. You have direct access to this application from the Oracle Blockchain Platform instance page in the Cloud Infrastructure Console so it's easy for you to add users and grant roles for your instance.

  1. Open the Cloud Infrastructure Console.
  2. Click the name of the Oracle Blockchain Platform instance.
    The Service Overview page displays showing the Web Tier Security Service and the Blockchain Service Manager.
  3. Click the manager for your instance.

    An overview page with Oracle Blockchain Platform instance details is displayed.

  4. Click the link next to IDCS Application and log in with your Oracle Identity Cloud Service credentials if prompted.

    An instance of Oracle Identity Cloud Service opens on the Details tab. Details about the application associated with your Oracle Blockchain Platform instance is displayed in Oracle Identity Cloud Service. From here, you can add users and groups, and assign them various permissions (application roles) in the Oracle Blockchain Platform instance.

The IDCS console has the following tabs used by the Oracle Blockchain Platform instance:

  • Details - Displays information about the Oracle Blockchain Platform instance, including the application ID, name, display name, and description.

  • Application Roles - Displays roles. Use this tab to assign users to roles in Oracle Blockchain Platform.

  • Groups - Displays user groups. You use this tab to create groups and then add one or more users or applications to the group.

  • Users - Displays users. You use this tab to add users and assign them to one or more groups or applications.

Add Oracle Identity Cloud Service Users

To access a Oracle Blockchain Platform instance that uses Oracle Identity Cloud Service for authentication, Oracle Blockchain Platform users must first have valid Oracle Identity Cloud Service credentials. Administrators manage the provisioning of users in Oracle Identity Cloud Service and perform the task of adding users.

To add users and provide them access to Oracle Blockchain Platform:
  1. Open the security application associated with the Oracle Blockchain Platform instance in Oracle Identity Cloud Service.
  2. Click the Identity Cloud Service Users tab at the top of the page (not the Users tab for the Oracle Blockchain Platform instance).
  3. Click Add and provide user details, then click Finish.

    The Details page is displayed for the user. An email will be sent to the user with login information.

Add Hyperledger Fabric Enrollments to a REST Proxy

To use the REST proxy API you can use the default enrollments or create a new enrollment by mapping an Oracle Identity Cloud Service user to a Hyperledger Fabric enrollment.

Prerequisite: you must have added the enrollment to the REST node in the Oracle Blockchain Platform console as described in Add Enrollments to a REST Proxy in Using Oracle Blockchain Platform
  1. Open the Oracle Identity Cloud Service console for your Oracle Blockchain Platform instance. The application you’re looking for is named: OABCSINST_<instance_name>
  2. On the Application Roles tab, search for the REST proxy user you created the enrollment for using the Oracle Blockchain Platform console. This role will be named: RESTPROXY_USER_${enrollment_name}
  3. Click the Action menu for this role, and select Assign Users.
  4. Select a user registered with Oracle Identity Cloud Service, and click OK.

Some important things to note about how Oracle Blockchain Platform handles REST proxy user roles:

  • The REST proxy will accept the request if the Oracle Identity Cloud Service user has only one RESTPROXY_USER_${enrollment_name} role in the Oracle Identity Cloud Service application.

  • The REST proxy will reject the request if the Oracle Identity Cloud Service user has multiple RESTPROXY_USER_$ {enrollment_name} roles in the Oracle Identity Cloud Service application.

    • If the Oracle Identity Cloud Service user doesn't have a RESTPROXY_USER_${enrollment_name} role, but has one or more roles such as RESTPROXY${1-4}_USER, the REST proxy will map this Oracle Identity Cloud Service user to the default enrollment.

    • The REST proxy will reject the request if the Oracle Identity Cloud Service user doesn't have a RESTPROXY_USER_${enrollment_name} or RESTPROXY${1-4} _USER role in the Oracle Identity Cloud Service application.

  • The REST proxy will cache the Oracle Identity Cloud Service application role states each 120 seconds for better performance, so assigning and revoking users to an Oracle Identity Cloud Service role may take 120 seconds to take effect.

Use a Third Party Identity Provider

By default Oracle Blockchain Platform uses Oracle Identity Cloud Service as its identity provider. However it is possible to use another identity provider and map it to Oracle Blockchain Platform user roles.

Oracle Cloud Infrastructure supports federation withOracle Identity Cloud Service and Microsoft Active Directory (via Active Directory Federation Services), and any identity provider that supports the Security Assertion Markup Language (SAML) 2.0 protocol. For detailed information about how to configure this federation, refer to Identity Providers and Federation.

To use a third party identity provider with Oracle Blockchain Platform:
  1. Configure federation and single sign-on between Oracle Identity Cloud Service and the third-party identity provider.
  2. Grant Oracle Blockchain Platform roles to the identity provider user IDs.
  3. Generate an access token for each identity provider user ID which uses REST to interact with Oracle Blockchain Platform.

Configure the Single Sign-on

The instructions in this section provide a very brief overview of the general process required to associate your third-party identity provider with Oracle Identity Cloud Service and configure single sign-on. Refer to the documentation of both products for more comprehensive information on how to complete this process.

In your third-party identity provider, create an integration between it and Oracle Identity Cloud Service. Ensure that you configure it to use SAML-based sign-on using SAML 2.0. Export your identity provider's metadata for SAML federation (the SAML signing certificate).

Create users in your identity provider and assign them access to Oracle Identity Cloud Service. Create matching users in Oracle Identity Cloud Service. You can then add a SAML identity provider in Oracle Identity Cloud Service and map it to your identity provider by importing the identity provider metadata.

Grant User Roles

In order for the users registered in your identity provider to access Oracle Blockchain Platform, you will need to grant them the appropriate user roles in Oracle Identity Cloud Service.
  • In order to access the Oracle Blockchain Platform console, they need to be either BCS Administrator or BCS User.
  • In order to use the REST proxy they need to be either RESTPROXY#_ADMIN or RESTPROXY#_USER.
  • In order to run chaincode transactions or perform Fabric certificate authority functions they need to be Administrator or Client.

For detailed information on user roles in Oracle Blockchain Platform, see Assigning Roles in Oracle Identity Cloud Service.

Generate Access Tokens

Any user accessing Oracle Blockchain Platform through the REST APIs requires an access token.

  1. Create a confidential application using a cURL command. Below is an example:
    curl -X POST -H "Content-Type:application/scim+json" 
    -H "Authorization: Bearer $ACCESS_TOKEN" ${IDCS_URL}/admin/v1/Apps 
    -d '{
    "displayName": "'${appDisplay}'",
    "realmName": "'${appDisplay}'",
    "isKerberosRealm": false,
    "description": "App desc '${appDisplay}'",
    "basedOnTemplate": {
    "value": "CustomWebAppTemplateId"
    },
    "isOAuthClient": true,
    "clientType": "confidential",
    "allowedGrants": ["client_credentials", "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:saml2-bearer", "refresh_token"],
      "allowedScopes": [{
        "idOfDefiningApp": "d55b5f55b5ec55555ef55555b5cb55d5",
        "fqs": "https://URL.com:443/external"
      }, {
        "idOfDefiningApp": "d55b5f55b5ec55555ef55555b5cb55d5",
        "fqs": "https://URL.com:443/internal"
      }, {
        "idOfDefiningApp": "d55b5f55b5ec55555ef55555b5cb55d5",
        "fqs": "https://URL.com:443/restproxy"
      }],
    
    "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:App"
    ],
    "isUnmanagedApp": true,
    "urn:ietf:params:scim:schemas:oracle:idcs:extension:kerberosRealm:App": {
    "realmName": "'${appDisplay}'realmName",
    "masterKey": "hello_world",
    "defaultEncryptionSaltType": "defaultSalt",
    "supportedEncryptionSaltTypes": [
    "supportedTypes"
    ],
    "ticketFlags": 1,
    "maxTicketLife": 100,
    "maxRenewableAge": 100
    }
    }'
  2. To make the confidential application visible to a user in the third-party identity provider, create a role:
    curl -X POST -H "Content-Type:application/scim+json" 
    -H "Authorization: Bearer $ACCESS_TOKEN"${IDCS_URL}/admin/v1/AppRoles 
    -d '{"displayName": "'${NEW_APP_ROLE}'", "adminRole": true, "description": "test role for userX", 
        "public": false, "availableToClients": true, "app": {"value": "'${APP_ID}'"},"schemas":
        ["urn:ietf:params:scim:schemas:oracle:idcs:AppRole"]}'
  3. Grant the role to the third-party identity provider user:
    curl -X POST -H "Content-Type:application/scim+json" 
    -H "Authorization: Bearer $ACCESS_TOKEN" "$IDCS_URL/admin/v1/Grants" 
    -d '{"app":{"value":"'${APP_ID}'"},
    "entitlement":{"attributeName":"appRoles","attributeValue":"'${ROLE_ID}'"},
    "grantMechanism":"ADMINISTRATOR_TO_USER","grantee":{"value":"'${USER_ID}'","type":"User"},
    "schemas":["urn:ietf:params:scim:schemas:oracle:idcs:Grant"]}'
  4. Sign on to Oracle Identity Cloud Service using the user ID from the third-party identity provider. You should now see the Oracle Blockchain Platform application as well as the confidential application you just created. Open the confidential application by double-clicking it.
  5. On the Details tab there is a Generate Access Token button. Click it to generate the access token you need to access the REST proxy.

Once you have the access token it can be added to the Oracle Blockchain Platform REST API cURL command headers as described in REST API for Oracle Blockchain Platform: Authentication.

Assigning Roles in Oracle Identity Cloud Service

This overview describes the roles that are relevant to Oracle Blockchain Platform. Anyone who uses or administers Oracle Blockchain Platform must be added in Oracle Identity Cloud Service and granted the correct user role.

Below are the roles that are available for Oracle Blockchain Platform.

User Role Granted Automatically to Instance Creator? Description
Administrator Yes The CA Admin role is the overall administrator for the Oracle Blockchain Platform cloud application.
BCS Administrator Yes See the table in Access Control List for Console Function by User Roles for a complete list of console functions available for this user role.
BCS User   See the table in Access Control List for Console Function by User Roles for a complete list of console functions available for this user role.
Client Yes This user role is assigned to Oracle Blockchain Platform participants to run transactions using the chaincode.
ORDERER Yes This role is assigned to the Fabric orderer node.
PEER Yes This role is assigned to a Fabric peer node.
RESTPROXY#_ADMIN Yes Grants user access to call administrative REST proxy endpoints.
RESTPROXY#_USER Yes Grants user access to call all REST proxy endpoints available on the REST proxy node with the same number.

Access Control List for Console Function by User Roles

The following table lists which console features are available to the BCS Administrator and BCS User roles.

Feature BCS Administrator BCS User

Dashboard

Yes

Yes

Network: list orgs

Yes

Yes

Network: add orgs

Yes

No

Network: Ordering service setting

Yes

No

Network: Export certificates

Yes

Yes

Network: Export orderer settings

Yes

Yes

Node: list

Yes

Yes

Node: start/stop/restart

Yes

No

Node: add/remove

Yes

No

Node: view attributes

Yes

Yes

Node: edit attributes

Yes

No

Node: view metrics

Yes

Yes

Node: view logs

Yes

Yes

Node: Export/Import Peers

Yes

No

Peer Node: list channels

Yes

Yes

Peer Node: join channel

Yes

No

Peer Node: list chaincode

Yes

Yes

Channel: list

Yes

Yes

Channel: create

Yes

No

Channel: add org to channel

Yes

No

Channel: Update ordering service settings

Yes

No

Channel: view/query ledger

Yes

Yes

Channel: list instantiated chaincode

Yes

Yes

Channel: list joined peers

Yes

Yes

Channel: set anchor peer

Yes

No

Channel: upgrade chaincode

Yes

No

Chaincode: list

Yes

Yes

Chaincode: install

Yes

No

Chaincode: instantiate

Yes

No

Sample chaincode: install

Yes

No

Sample chaincode: instantiate

Yes

No

Sample chaincode: invoke

Yes

Yes

CRL

Yes

No