Relying party usage

You will need to configure your application as an OpenID connect relying party in order to authenticate against the Rolka Loube authentication provider. In short, you are delegating authentication to the provider, which will return a signed token to your application containing key information about the user.

Access model overview

Products have a set of roles, which are used to separate operations into logical groups.

Tenants are organizational units of applications and their users. Tenants usually represent a customer.

Users may be members of one or more tenants. For each tenant they are in, they have zero or more roles for each product. This means that users might have access to a product in multiple tenants, but their set of roles might be different between them. Be careful when developing a multi-tenant application.

Applications belong to one tenant and one product. Applications authenticate with the provider using one or more sets of client credentials.

Tenant in this context will be the same Id as the Entity Id in the NDBEDP Centralized Database API.

OpenID Connect overview

OpenID Connect is a layer over OAuth 2.0 that allows you to request that a provider authenticate a user and provide certain information (“claims”) about them. The flow is as follows:

Your application constructs an authorization URL using information about the provider and the scopes it needs.
Your application redirects the end-user to the authorization URL.
The provider authenticates the user and decides if your application has access to the given scopes.
The provider redirects the user to a callback URL on your application with either an access token or an error.
Your application either handles the error or uses the access token to request an id token for the user.

Your client library should handle most of the cryptography and key ceremony for you.

Client configuration

You need to provide your client library with information about the provider to authenticate against it. Generally, this will include your client ID and secret, the issuer URI, and what scopes you want to request.

Issuer

The issuer URI is https://rlauthproviderqaapp.azurewebsites.net/oidc. (This is the test instance. As the provider is still under heavy development, there is no production instance.)

The provider supports OpenID Connect Discovery. This means that most clients will be able to discover information about the provider (token endpoint, signing keys, etc.) given only the issuer URI. If your library doesn’t support this and insists that you manually provide endpoints and keys, you can obtain the information yourself by looking at the discovery document: https://rlauthproviderqaapp.azurewebsites.net/oidc/.well-known/openid-configuration

An implementation detail not in the OpenID specification, but guaranteed by the provider, is that the first key in the key set returned at jwks_uri is the public key corresponding to the key used by that instance of the provider to sign tokens. While older keys will be rotated out of the set as necessary, you can force users to log in whenever keys are rotated by only accepting tokens signed with the first key in the set. Note that this behavior would be in violation of the OpenID specification and should only be used to fulfill Federal Information Security Management Act of 2002 (FISMA) requirements if such requirements apply to your application and there is no other way to meet them.

Production URI’s will be added once the system goes live.

Client ID and secret

Client ID and secret is a pair of GUIDs that your application uses as credentials to get tokens from the provider. Eventually, there will be an automated process for obtaining these, but for now, you will need to contact Rolka Loube to obtain a client ID and secret. To receive these GUIDS, you will need to provide us the name of the application, login redirect URL(s), and logout redirect URL(s).

The Client ID is not stable and will be different for each pair of credentials. The Application ID is the stable ID that does not change for an application throughout its lifetime.

Scopes

Scopes is the access to information the provider has about the user that your application is requesting. Currently, there are only four meaningful scopes, three of which are standard OpenID scopes:

openid: Signifies your application is using OpenID connect. This scope must always be specified. (Typically, your library will add it automatically.) Returns the sub claim with a GUID that uniquely identifies the user.
profile: Returns the user’s display name as the name claim. Keep in mind that end-users may set this to whatever they want.
email: Returns the user’s email address as the email claim. Also returns email_verified as always true; this will eventually specify whether the user has verified their email address or not.

The last scope is not part of the OpenID spec and is how the provider implements role-based access.

roles: Returns the roles the user is part of as an array of role objects (see below) in the https://rolkaloube.com/roles claim. Any role object may have an empty array of roles if the user has no roles in that tenant.
There will be one role object per tenant in unspecified order. The schema of a role object is as follows:
JSON
```
{
  "tenant": {
    "id": "tenant guid",
    "name": "human-readable tenant name"
  },
  "roles": ["array", "of", "role", "names"]
}
```

Relying party initiated logout

You can request that the provider log out the end-user and optionally redirect back to your application. To do so, redirect the end-user to the URL specified in the end_session_endpoint value of the discovery document. You can specify optional URL parameters for additional behavior:

id_token_hint: Provide an ID token if you have one. This will cause the provider to display your application name to the end-user and allow use of the post_logout_redirect_uri parameter.
post_logout_redirect_uri: After logging out the user, the provider will redirect them to this URL. You must provide a valid ID token in id_token_hint for this to work, and the URL must match one you have previously registered with the provider. If this parameter is not provided, the provider will show the end-user a message telling them they have logged out without redirecting them.
state: If provided alongside post_logout_redirect_uri, the state parameter will be passed back to your application at the redirect URL.

Relying party initiated logout is not a security feature!

Relying party initiated logout is only a convenience feature; the end user can simply refuse to log out. In this case, even if you destroy your application’s session and redirect the end-user through the authorization code flow again, they may not have to enter a username and password.

If you need to force the user to enter their username and password again (e.g. due to regulations), destroy your application’s session and follow the authorization code flow using the max_age or prompt parameters on the authorization URL instead of using relying party-initiated logout.

Relevant specifications

https://openid.net/specs/openid-connect-core-1_0.html

https://openid.net/specs/openid-connect-discovery-1_0.html

https://openid.net/specs/openid-connect-rpinitiated-1_0-01.html