# OpenID Connect
URL: https://docs.valsight.ai/openid-connect/
Description: To configure the Valsight application to use the OpenID Connect SSO, edit conf/config.yml and restart the server after making changes.
To configure the Valsight application to use the OpenID Connect SSO, edit *conf/config.yml* and restart the server after making changes.
To enable OpenID Connect login configure the following value:
| Configuration Key (loginMethodConfigurations → openIdConnect →) | Description | Example Value | Default Value |
| --------------------------------------------------------------- | ----------------------------------------------------------- | ------------- | ------------- |
| enabled | Whether OpenID Connect authentication should be used or not | true | false |
To configure an OpenID Connect client enter the following configuration keys:
```
spring:
security:
oauth2:
client:
registration:
openIdConnect:
.....
```
Then configure the OpenID Connection client values as follows:
| Configuration key | Description | Example | Default |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | -------------------------------- |
| `client-id` | OAuth 2.0 client identifier, valid at the authorization server | `jmxDcfi1gEffVMktJ` | n/a |
| `client-authentication-method` | The type of client authentication to perform with the authorization server. See [Client authentication methods](#client-authentication-methods). | `client_secret_basic` | `client_secret_basic` |
| `client-secret` | Client secret token, provided by the authorization server. Since 6.3.0 this is no longer mandatory unless `client_secret_basic` is the client authentication mode. | `aZWAuRZUSxT-Sh8-xDLdHI` | n/a |
| `scope` | Comma-separated list of scopes to request, when additional claims are needed | `openid, email, profile` | n/a |
| `provider` | The name of the OpenID Connect provider to use. Required unless a provider with the registration id `openIdConnect` exists. | `openIdConnect` | n/a |
| `valsightOpenIdConnectProperties → userProfileMapping → username` | The claim used to uniquely identify a user. Must always be present in the provider's response, and unique per user. See [Claim names are case sensitive](#claim-names-are-case-sensitive). | `preferred_username` | `sub` |
| `valsightOpenIdConnectProperties → userProfileMapping → email` | The claim that contains the user's e-mail address. Optional. | `email` | n/a |
| `valsightOpenIdConnectProperties → userProfileMapping → fullName` | The claim that contains the user's full name. Optional. | `name` | n/a |
| `valsightOpenIdConnectProperties → loginSuccessfulUrl` | The absolute URL, starting with `http` or `https`, of the application's main page. The user is redirected there after a successful login. | `https://valsight.example.com/` | n/a |
| `valsightOpenIdConnectProperties → forceGroupsOverage` | Forces the application to always use the `https://graph.microsoft.com/v1.0` API to fetch the user's groups. No effect unless `groupsClaim` is enabled. Optional. | `true` | `false` |
| `valsightOpenIdConnectProperties → acr_values` | Passes additional authentication-related information to the user service. Optional. | `myvalue1:myvalue2:myvalue3:myvalue4` | n/a |
| `valsightOpenIdConnectProperties → mandatoryClaims` | Customizes which claims must be present, and with which values, beyond those requested by the OpenID Connect specification. See [Mandatory claims](#mandatory-claims). Optional. | See [Mandatory claims](#mandatory-claims) | n/a |
| `valsightOpenIdConnectProperties → groupsClaim` | The claim holding the groups the user belongs to. See [Group synchronization](#group-synchronization). Optional. | `groupsInOpenIDConnectResponse` | n/a |
| `valsightOpenIdConnectProperties → requiredGroupNamePrefix` | Removed in 6.0.0. See [Removed: requiredGroupNamePrefix](#removed-requiredgroupnameprefix). | `AcceptedGroup_` | n/a |
| `valsightOpenIdConnectProperties → userInfoEndpointScopes` | Scopes that are accessible only from the user info endpoint, not from the token. See [User info endpoint scopes](#user-info-endpoint-scopes). | See [User info endpoint scopes](#user-info-endpoint-scopes) | `profile, email, address, phone` |
### Client authentication methods
The supported forms of authentication are `client_secret_basic` and `private_key_jwt`.
With `client_secret_basic` a `client-secret` must be provided; with `private_key_jwt` a `privateRSAKeyPath` must be provided instead. For more on `private_key_jwt`, see [OAuth 2.0 with private key JWT client authentication](/oauth-2-0-with-private-key-jwt-client-authentication/).
### Claim names are case sensitive
Ensure the configured string matches the IdP claim name exactly. This applies to every `userProfileMapping` entry, to `groupsClaim`, and to the `claim` values under `mandatoryClaims`.
### Mandatory claims
Every claim configured here must be present in the provider's response and carry the specified value. Where a claim has multiple values in the response — a list of the user's groups, for example — one of those values must match the configured value exactly.
MIGRATETOKEN1ENDTOKEN
### Group synchronization
Setting `groupsClaim` turns on group synchronization. If the claim is absent or empty, groups must be managed inside the application instead. The value should be a claim name that contains the groups the provider supplies.
Group matching then happens as follows:
1. Read the groups from the OpenID Connect response.
2. Create groups that are missing in the application.
3. Add the user to all groups from the response.
4. Remove the user from all groups not in the response.
This functionality never automatically deletes groups in the application.
### Removed: requiredGroupNamePrefix
Available since 5.9.1, removed in 6.0.0 and replaced by `loginMethodConfigurations → commonSSOOptions → requiredGroupNamePrefixes`. See [Common SSO Options](/common-sso-options/).
Before 6.0.0 this determined whether group names had to carry a given prefix to be recognised by the application: any group name in the OpenID Connect response not starting with the value was treated as absent. When `mandatoryGroupName` was also set, the mandatory group name had to carry the required prefix.
### User info endpoint scopes
To stop the user info endpoint being invoked at all, populate this list with none of the scopes listed under `scope`. Setting it to an empty list means the user info endpoint is always invoked.
Available since 6.0.26.
MIGRATETOKEN2ENDTOKEN
To configure an OpenID Connect provider enter the following configuration keys:
```
spring:
security:
oauth2:
client:
provider:
openIdConnect:
.....
```
Then configure the OpenID Connection provider values as follows:
| Configuration Key (….provider.openIdConnect →) | Description | Example Value | Default Value |
| ---------------------------------------------- | ----------------------------------------------------------- | ---------------------------------- | ------------- |
| issuer-uri | Identifier for the Issuer of the authorization response. | | n/a |
| authorization-uri | The Authorization endpoint of the OpenID Connect flow | | n/a |
| token-uri | The Token endpoint of the OpenID Connect flow | | n/a |
| jwk-set-uri | The endpoint that contains certificates to verify the token | | n/a |
#### Full example YAML configuration
Below is an example of all the available configuration keys for OpenID connect, with no values supplied except where stated:
```
spring:
security:
oauth2:
client:
registration:
openIdConnect:
client-id:
client-secret:
scope:
valsightOpenIdConnectProperties:
userProfileMapping:
username:
email:
fullName:
forceGroupOverage:
loginSuccessfulUrl:
mandatoryClaims:
#example value
group: groupName
acr_values:
groupsClaim:
requiredGroupNamePrefix:
userInfoEndpointScopes:
provider:
openIdConnect:
issuer-uri:
authorization-uri:
token-uri:
jwk-set-uri:
```
## Logging
For logging purpose, add in the log level view (Configuration UI), the following package:
* `org.springframework.security`
* `org.springframework.security.oauth2`
* `com.valsight.authentication.oauth`
* `com.valsight.services.authentication.SSOService`
* `com.valsight.authentication`
* `org.springframework.web.client`
Set the log level to DEBUG
### Redirect/callback URL
When configuring the IdP the redirect/callback URL for the application is:
\//login/oauth2/code/openIdConnect
### Reverse proxy configuration
If the application is running behind a reverse proxy it will be required to configure the reverse proxy such that the OpenID connect authentication flow can be performed A guide to doing this can be found here: [Reverse Proxy](/reverse-proxy/)