Configuring authentication

Use this guide to configure authentication and authorization for HTTP-RPC, using basic authentication or Azure Active Directory (AD) single sign-on (SSO).

Most of the endpoints exposed via HTTP-RPC require authentication. getProtocolVersion is the only endpoint that doesn’t require authentication.

You can test the authentication functionality using Swagger UI (if enabled):

Authenticate on Swagger UI

Nodes support Basic authentication and Azure Active Directory (AD) single sign-on (SSO) .

Set up basic authentication

You can use authenticated HTTP-RPC endpoints with basic HTTP authentication using the username/password combinations set up for RPC use. To configure user credentials in the node.conf file or through the use of an external database, see the guide on managing RPC security in Corda 4.

This feature is enabled by default and cannot be disabled.

Configure authorization for basic authentication

Authorization in the Corda 5 Developer Preview uses the same Apache Shiro-based solution that was available in Corda 4. For details on how to configure this, see the guide on managing RPC security in Corda 4.

Test your configuration

You can test your configuration using Swagger UI:

Basic authentication on Swagger UI

Set up Azure AD SSO

You can set up your node to use Azure Active Directory (AD) for single sign-on (SSO). Authorized users who access HTTP-RPC functions on the node can use their Azure AD credentials to stay logged in to any applications that use the HTTP-RPC API.

  1. Configure the Azure AD tenant that serves as an identity provider and the node to enable HTTP-RPC endpoints to support Azure AD-based authentication.

  2. Pass an Azure AD ID token or access token as a Bearer Token with the HTTP-RPC requests. The node verifies these properties/claims of the token:

    • Expiration date.
    • Issuer (should be a valid Microsoft Identity Platform value).
    • Audience (should be the clientId of the node).
  3. Test this functionality using Swagger UI. The data flow should look like this:

Example data flow

Configure Azure

These steps describe a basic setup. Configuring a production setup may include additional steps, such as those for user access management and permission sets (scopes).

To complete the configuration of your node using the Azure Portal :

  1. Navigate to the register an application screen (Manage > App registration > New registration).

  2. Complete the online form to represent your node:

Register a new application

  1. Make a note of the Application (client) ID and Directory (tenant) ID. You need these to configure your node.

Record application details

  1. Set authentication to ensure only accounts in this directory can use the app:

Set authentication

  1. Make the menu selection: Manage > Authentication, Platform configuration > Add a platform, Configure platforms > Single-page application.
  1. Set the redirect URL to http(s)://<host>:<port>/webjars/swagger-ui/3.44.0/oauth2-redirect.html, and select implicit grant as ìd_tokens.

  2. Under Manage, select API permissions, and add user permissions. You must apply User.Read as a minimum, but you can select scopes with wider permissions to suit your requirements.

Add user permissions

You have finished configuring Azure.

Configure your node

Azure AD SSO is configured via a top-level object named httpRpcSettings in node.conf:

"httpRpcSettings": {
    ...
    "sso": {
        "azureAd": {
            "clientId": "<client_id>",
            "clientSecret": "<client_secret>"
            "tenantId": "<tenant_id>",
            "principalNameClaims": ["<claim1>", "<claim2>"]
        }
    }
}

Configuration options include:

Field Required? Value
clientSecret Optional Auto fills the client-secret field on the Swagger UI authentication page when a non-public client flow is configured on Azure. This field will be exposed on Swagger UI.
principalNameClaims Optional A prioritized list of claims that the node retrieves from the Azure AD-generated JSON web token (JWT) to then identify the user and fetch their permissions. Defaults to ["upn", "preferred_username", "email", "appid", "azp"].

Configure authorization for Azure AD SSO

Permissions are retrieved using the same Apache Shiro-based solution as for basic authentication . However, the actual name of the user is derived from Azure claims.

To specify SSO permissions, add the email address that is associated with their SSO-authenticated user profile to the node.conf file.

"rpcUsers": [
    {
        "user": "user1@company.com",
        "permissions": [
            "ALL"
        ]
    }
]

For Azure AD SSO authentication, JWT tokens are used to verify a user’s identity. Therefore, users listed in the Shiro database should not specify a password in the node.conf file.

Test your configuration

You can test your setup using the Swagger UI:

Azure AD authentication on Swagger UI

Was this page helpful?

Thanks for your feedback!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.

We're sorry this page wasn't helpful. Let us know how we can make it better!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Create an issue

Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.