# Using federated accounts

You can configure UDiTH Portal account management to use an external authentication provider, for example ADFS, through one of the authentication protocols supported by Keycloak.
This delegates authentication to the selected identity provider.

This document shows the configuration process by using Microsoft Azure as an example.

## Basic configuration

1. Create a new **Identity provider** entry in the Keycloak administration UI.

	- Select the application realm, default: **uws**.
	- Go to **Configure / Identity providers**.
	- Add a new **User-defined** provider: **OpenID Connect v1.0**.

	<table>
	<tr><th>Field</th><th>Description</th></tr>
	<tr><td>

	Alias

	</td><td>

	Identifies the provider. This value can be chosen freely.

	</td></tr>
	<tr><td>

	Discovery endpoint

	</td><td>

	Path to the `.well-known/openid-configuration`, for example for Azure ADFS: `https://login.microsoftonline.com/<tenant id>/v2.0/.well-known/openid-configuration`

	</td></tr>
	<tr><td>

	Client ID

	</td><td>

	Obtained from the Azure app registration.

	</td></tr>
	<tr><td>

	Client Secret

	</td><td>

	Can be generated in the Azure app registration under **Manage / Certificates & secrets**.

	</td></tr>
	<tr><td>

	Advanced/Backchannel logout (optional)

	</td><td>

	Recommended value: **true**. This ensures that logging out of UDiTH Portal does not also log the user out of the identity provider.

	</td></tr>
	</table>

	<img src="./media/keycloak_add_identity_provider.png" width="789" height="484">

2. Set up a new app registration in Microsoft Azure.

	The **Redirect URI** can be copied from the first field entry in the Keycloak registration, for example `http://localhost:8080/realms/uws/broker/oidc/endpoint`. Enter it in the **Redirect URI** field of the Azure app registration.

	![](./media/oidc2.png)

3. Configure API permissions.

	On the Azure API permissions page, add `email`, `openid`, `profile`, and `User.Read` as delegated Microsoft Graph permissions.

	![](./media/oidc2-permissions.png)

4. Try logging in to UDiTH Portal.

	There should now be a new sign-in option in the Keycloak login screen.

## Additional configuration options

### Use group synchronization

Allow UDiTH Portal to extract user groups from the external provider. The user groups are synchronised when UDiTH Portal is restarted or when **ForceRefresh** is called in the Admin UI.

Create the groups to be synchronised in UDiTH Portal at `../administration/groups`.
Assign the **Group GUID** found in Azure Portal to the new group. The group connection is established by using this GUID value.

<img src="./media/UPVWebServices_oidc_group_guid.png" width="691" height="220">

Allow the group claim to be requested in Azure Portal:

On the **Token Configuration** page:

- add an additional `groups` claim.

<img src="./media/UPVWebServices_oidc_groupclaim.png" width="764" height="303">

Relevant for Keycloak major version 25 and later:

Create the `groups` attribute, as unmanaged attributes are no longer allowed by default.
To do this, go to **Realm Settings / User profile** and create an attribute named **groups**.

In the Keycloak **Identity provider** settings, add a new entry under **Mappers**.
This transmits the information from the **groups** claim to the user's attribute field. UDiTH Portal expects the **User attribute name** to be set to **groups**.
If your identity provider uses a different group claim name, you can define the required **Claim** name in this mapper. Note that the **Claim** value is case-sensitive.

<img src="./media/keycloak_add_mapper.png" width="789" height="484">

**Sync mode** defines when the mapper is executed.

Options:

- **Force**: Updates on every login. Recommended.
- **Import**: Updates only when the user is created in Keycloak for the first time.

### Import roles

You can also use a new **Mappers** entry for this.

This is done by using the **Claim to Role** mapper.

### Metadata customization

You can also use a new **Mappers** entry for this.

This is done by providing the required **User attributes**. Relevant predefined mappers for this use case are **Attribute Importer** and **Hardcoded Attribute**.
For example, if you provide a user attribute named **email**, this corresponds to the user's email entry.

<img src="./media/keycloak_add_mapper_attribute.png" width="789" height="484">

Keycloak claims:

- username
- firstName
- lastName
- email
- emailVerified, which does not appear to work at the moment

### Troubleshooting

You can use the following Keycloak start command to enable logging of user claims during sign-in:

`kc.bat start --log-level="INFO,org.keycloak.social.user_profile_dump:debug"`