# Single-Sign-On

Allow single sign-on for users on an Exoscale account using an Open ID Connect, also known as OIDC.
identity provider. SSO organization connect for Exoscale is available to every organizations.

## Activation

Accessible to users with **OWNER** user role in the **IAM** section of the main
navigation, under **SSO**.

![](sso-activation.png "SSO activation")

## Configuration

Accessible to users with **OWNER** user role in the **IAM** section of the main
navigation, under **SSO**.

![](sso-configuration.png "SSO configuration")

You need to enter:

* your OIDC `Client ID`
* the OIDC `Issuer URL`
* your OIDC `Client Secret`

This is the URL you need to authorize on the OIDC provider side: `https://portal.exoscale.com/sso-authenticate/<sso-org-name>`

![](sso-shareable.png "SSO shareable endpoints")

## Login

The URL for the SSO login page: `https://portal.exoscale.com/sso-login/<sso-org-name>`

![](sso-login.png "SSO login")

When a user logs in an organization using SSO, a new, unique user is created inside this organization with the **TECH** role.

The username is a universally unique identifier (or UUID) to allow for a standard non-SSO user with the same email address.

## Authorization

You can authorize in two ways:

* Use an ID token introspection with a [Common Expression Language](https://github.com/google/cel-spec) (or CEL) query.
* Set up your own proxy with a [DEX](https://dexidp.io/) server or equivalent.

### Authorization with ID token introspection

Enter two values to perform ID token payload introspection to authorize a user:

* `OIDC Additional Claims` which contains claim names (space separated)
* a `Common Expression Language Authorization Expression` which is evaluated at login time against the ID token payload.

![](sso-authorization.png "SSO authorization")

#### OIDC additional claims

The standard claims which are always part of the ID token payload are:

* `openid`
* `profile`
* `email`

If you need to introspect additional claims, you need to enter them in the `OIDC Additional Claims` field.

#### Common Expression Language Authorization Expression

This Common Expression Language query will be evaluated at login time against the ID token payload.

The CEL authorization expression must return the UUID of the desired IAM Role for the user.

```bash
email.endsWith('@exoscale.com') ? 'dc097e90-4636-4d2a-a629-670ab4395209' : false
```

The role of the SSO users will be updated accordingly over time with the return value of the CEL expression. This means that by updating the IAM Role UUID in the above example, the user would be assigned to it.

Any return value that is not a valid IAM Role UUID will deny access to the platform.

![](sso-login-fail.png "SSO Login failed")

#### Removal of SSO users

Every time a new SSO user is recognized by Exoscale, a new special account is created on the platform. You can see all of your Organization's users in the user management view in the web portal: `IAM` > `Users`.

In order to fully remove a SSO user, it is not enough to remove it from your Exoscale Organization, you will also need to prevent his ability to login via the OIDC provider, or the user will simply be recreated at its next login.

##### Common Expression Language resources
* [Introduction](https://github.com/google/cel-spec/blob/master/doc/intro.md)
* [Language reference](https://github.com/google/cel-spec/blob/master/doc/langdef.md)