Add Roles and Permissions
Add Role-Based Access Control (RBAC) for organisations and users within an ecosystem. Define Roles, granting permissions to chosen participants within by using Role Metadata.
Prerequisites
-
Domains available and configured within the platform.
Add a Domain if there is no available already.
-
Get an Access Token with the
directory:websitescope–if you want to create or manage Roles and their Metadata using Connect's APIs.
Create Role
Roles can be created only for an already existing authorization domain. A role cannot exist by itself–it needs to be associated with a domain.
-
Select Reference Data > Domains and Roles.
-
Use the dropdown to expand the Domain where you want to add a role.
-
Select + Add Role.
-
Fill in all the required fields and save.
| Field Name | Description |
|---|---|
| Authorisation Domain Name | Common name of the associated Domain |
| Role Name | Name of the role |
| Role Type | Type of the Role Federation: Defining how an organisation client application's software statement is presented to the broader ecosystem. Federation roles influence the interaction pattern between the client application and the ecosystem. It shapes the client endpoint behavior and its relations with Authorisation Servers. Directory: Directory roles determine the manner in which an organisation's client applications communicate with the Connect's APIs. Modifications to Directory roles are applied across all client applications registered within a framework. |
| Is this role exclusive? | Controls whether an organisation can have other roles assigned. If an organisation has an exclusive role assigned, it cannot have any other role assigned. |
| Description | Description of the Role |
Add Role Metadata
-
Select Reference Data > Domains and Roles.
-
Using the dropdown button, expand the Domain where you want to configure a role by defining its metadata.
-
Select the role for which you wish to add metadata.
-
Select New Metadata.
-
Fill in the fields defining the role metadata.
Metadata Description Entity Type Type of the entity to which the metadata applies to. Read more about available entity types. Claim Name Metadata type - specific information the client application is able to request or the authorization server to support. Read more about metadata types. Policy Operator Action on the metadata parameter: a value check, value modification, or both. Read more about policy operators. Data Type Type of the data stored in metadata. Value Value of the role's metadata. -
Save new role metadata.
Available Entity Types
| Entity Type | Description |
|---|---|
| OpenID Provider | The OP is the authorization server / identity provider, in an OpenID Connect flow. It authenticates the user and issues the ID Token and Access Token. |
| OAuth Authorization Server | The authorization server is the system that handles user authentication and issues tokens (ID Tokens, Access Tokens, Refresh Tokens). It’s responsible for verifying the user’s identity and providing the client app with the information it needs. |
| OpenID Relying Party | The RP is the client application that uses OIDC. It redirects the user to the OP for authentication and then relies on the returned ID/access token. |
| OAuth Client | The client application is the app gets authorization from the user and authenticates to the authorization server. Uses the returned tokens to know who the user is and to call APIs. |
While OpenID Provider and OAuth Authorization server or Relying Parties and OAuth clients seem the same, there are some subtle differences.
An OpenID Provider is always an OAuth Authorization Server, but an Authorization Server is not always an OpenID Provider. An OpenID Relying Party is always an OAuth client, but not all OAuth clients are Relying Parties.
In both cases, the difference lies in the metadata profile issued for the given entity type. On Raidiam Connect, there are no functional differences between both pairs of types but different sections of metadata being issued in case OpenID Federation is being used as the underlying Trust Scheme in the Trust Framework.
For example, OAuth Dynamic Client Registration
Metadata
is issued only for OpenID Relying Parties–which does not need to be a case
for OAuth client. For OpenID Provider, the metadata defined in OpenID Connect
Discovery will be
issued, which may not be the case for an OAuth authorization server.
Available Metadata Types
claim
| Entity Type | Metadata Type description | Example |
|---|---|---|
| OpenID Provider / OAuth Authorization Server | Specific pieces of information the OP/Authorization Server may issue as parts of ID tokens/Access Tokens to convey information about the client, user, or authentication event. | name, family_name |
| OpenID Relying Party / OAuth Client | Specific pieces of information requested by organisation's client applications to be included within the requested access and/or ID tokens to convey information about the client, user, or authentication event. | name, family_name |
claim_in_verified_claims
Verified claims differ from regular claims by enabling strong assurance of a claim according to the OpenID Connect Specification for Identity Assurance.
| Entity Type | Metadata Type description | Example |
|---|---|---|
| OpenID Provider / OAuth Authorization Server | Specific and verified pieces of information the OP/Authorization Server may issue as parts of ID tokens/Access Tokens to convey information about the client, user, or authentication event. | name, family_name |
| OpenID Relying Party / OAuth Client | Specific and verified pieces of information requested by organisation's client applications to be included within the requested access and/or ID tokens to convey information about the client, user, or authentication event. | name, family_name |
For example of how verified claims look like, see the OIDC for Identity Assurance specification section #5.
scope
| Entity Type | Metadata Type description | Example |
|---|---|---|
| OpenID Provider / OAuth Authorization Server | Scopes the authorization server can support in order to enable client access. | email, openid, profile |
| OpenID Relying Party / OAuth Client | Used by client applications to specify the access scopes the client requests from the OP/authorization server. | email, openid, profile |
It is considered a best practice to always limit the scopes requested only to the absolute necessary ones for security purposes.
If you are adding metadata to a role of the directory type and wish to
enable client applications to access Connect's APIs, Raidiam's OAuth
Authorisation Server accepts three
values: directory:website, directory:software, and directory:admin.
Within Connect, all client applications are by default assigned the
directory:software scope to enable them to access the platform's APIs.
response_type
| Entity Type | Metadata Type description | Example |
|---|---|---|
| OpenID Provider / OAuth Authorization Server | Defines the response types the authorization server can use when responding to token or authorization requests. | code token |
| OpenID Relying Party / OAuth Client | Determines the response type the client application can request while making requests to the Authorisation Server's /authorization and /token endpoints. | code token |
One of: code, code token, code id_token, id_token token, code id_token token For more information about response types and their
detailed descriptions, see the OAuth 2.0 Multiple Response Type Encoding
Practices specification section
#5.
grant_type
| Entity Type | Metadata Type description | Example |
|---|---|---|
| OpenID Provider / OAuth Authorization Server | Defines the grant types the authorization server must support and use for client application access | authorization_code |
| OpenID Relying Party / OAuth Client | Specifies the OAuth grant type (flow) the client application can use while requesting authorization from the user or token from the authorisation server. | authorization_code |
If you are adding metadata to a role of the directory type and wish to
enable client applications to access Connect's APIs, Raidiam's OAuth
Authorisation Servers accepts two
values: authorization_code, or client_credentials.
Within Connect, all client applications are by default assigned the
client_credentials flow to enable them to access the platform's APIs.
is_resource_server
Specifies whether the entity represents a resource server or not.
One of: true, false
authorization_details_type
| Entity Type | Metadata Type description | Example |
|---|---|---|
| OpenID Provider / OAuth Authorization Server | Defines the fine-grained permissions (authorization details types) the authorization server can use while issuing tokens to client applications | payment_amount |
| OpenID Relying Party / OAuth Client | Enables client applications to specify their fine-grained authorization requirements while using the OAuth 2.0 Rich Authorization Requests (RAR) grant type. | payment_amount |
Available Policy Operators
| Operator | Description |
|---|---|
| value | The value must match exactly what is defined. |
| default | Provides a default value when none is supplied elsewhere. |
| one_of | The value must be one item from the allowed list. |
| subset_of | The value must be a subset of the allowed policy list. |
| superset_of | The value must contain all required items, but may include more. |
| add | Appends values to the policy’s existing list. |
| remove | Removes values from the policy list. |
| subset_of_keys | The keys of an object must be a subset of allowed keys. |
| superset_of_keys | The keys must include all mandatory keys. |
| one_of_keys | The object must contain one of allowed keys. |
Delete Role
For security purposes, Raidiam enables Global Administrators only to soft-delete Roles by disabling them.
You can disable an Role by selecting the Disable button
(access forbidden sign under Actions) or by using the Update Authorisation
Domain Role
and
setting the role's status to inactive.
Manage Roles Using APIs
Raidiam Connect allows organisations to integrate with the following APIs for Authorisation Domain Management:
For Metadata, you can integrate with the following APIs:
