iam.md

Identity Federation

see: User identity federation -XDev project Confluence space

Collaborate use Keycloak as an Identity broker to make users able to work with identity providers from which he can authenticate using his organization credentials.

An Identity Broker is an intermediary service that connects multiple service providers with different identity providers. As an intermediary service, the identity broker is responsible for creating a trust relationship with an external identity provider in order to use its identities to access internal services exposed by service providers.

Configuring Keycloak

The running keycloak instance is the an XDev - Keycloak container image. During development cycle, the Keycloak Administration console user interface can be used for configuration and test purposes using Keycloak Admin credentials:

• Open Lens
• In Workloads / Pods, select the pod named col-keycloak-0, in the right panel you will find the Admin user credentials as environment variables:
  • user: KEYCLOAK_ADMIN_USER
  • password: KEYCLOAK_ADMIN_PASSWORD

Identity administrator onboarding

While deploying your application instance for the first time, you will need to define a first _ identity admin user_ to configure how others users will connect to your application.

• Use predefined identity admin (aka Eric) available user .
• Configure an identity provider
• Ask one of your organization user (aka. Fabian) to make a first login using the configured identity provider.
• Use the Eric account to update Fabian roles with the Service identity provider administrator role.
• Disable all the predefined users, and so only Fabian account can access your application until new users make a first login and Fabian give them a role (or they already have a default role if a role mapper has been configured with the organization identity provider).

Connect Identity Provider

As Keycloak is an Identity Broker it is possible to define multiple Identity Providers (e.g. Google, GitHub...) in its configuration. There is multiple ways to add an Identity provider into your Keycloak instance :

• Use the Keycloak Administration console user interface:
  • According to Keycloak Official Documentation you can follow step described to integrate the Identity Provider of your choice.
• Pre-configure the Keycloak realm configuration file:
  • You can provide a list of identity provider following the Keycloak Identity Provider Representation
• Use The Keycloak Rest-API:
  • By using the Keycloak Rest-API . You will first need to retrieve a JWT for the keycloak admin user ( cf. Get a JWT). Following example illustrate how to add a GitHub provider.

curl --location --request POST 'http://psa.localhost/auth/admin/realms/collaborate/identity-provider/instances' \
--header 'Authorization: Bearer {{YOUR_JWT_ACCESS_TOKEN_GOES_HERE}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "alias": "xdev-github",
    "displayName": "Login with XDev GitHub",
    "providerId": "github",
    "enabled": true,
    "updateProfileFirstLoginMode": "on",
    "trustEmail": true,
    "storeToken": false,
    "addReadTokenRoleOnCreate": false,
    "authenticateByDefault": false,
    "linkOnly": false,
    "firstBrokerLoginFlowAlias": "first broker login",
    "config": {
        "syncMode": "IMPORT",
        "clientSecret": "<<CLIENT_SECRET>>",
        "clientId": "<<CLIENT_ID>>",
        "guiOrder": "0",
        "useJwksUrl": "true"
    }
}'

Role mapping: Define a default user role for user authenticated from identity provider

You can define a default role to users that come from an external identity provider by defining a role mapper:

curl --location --request POST 'http://psa.localhost/auth/admin/realms/collaborate/identity-provider/instances/github/mappers' \
--header 'Authorization: Bearer {{YOUR_JWT_ACCESS_TOKEN_GOES_HERE}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "default pending_asset_owner for github",
  "identityProviderAlias": "xdev-github",
  "identityProviderMapper": "oidc-hardcoded-role-idp-mapper",
  "config": {
    "syncMode": "IMPORT",
    "role": "pending_asset_owner"
  }
}
'

Get a JWT

The initial user configuration is made by customizing the Keycloak user configuration file. Pre-configured users and roles are available:

username	e-mail	password	roles
Eric	[email protected]	admin	service_identity_provider_administrator
Sam	[email protected]	admin	data_service_provider_administrator
David	[email protected]	admin	business_service_provider_operator
Paul	[email protected]	admin	business_service_provider_administrator
Gabriel	[email protected]	admin	business_network_operator

Collaborate define a pre-configured frontend OpenID Connect Client using openid-connect protocol for single-sign-on.

To get a JWT token you can make a request:

curl --location --request POST 'https://col.localhost/auth/realms/collaborate/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=sam' \
--data-urlencode 'password=admin' \
--data-urlencode 'client_id=frontend'

User roles

The target user roles definition is available on the Stakeholders and user roles - XDev Collaborate Confluence page