# Single Sign-On (SSO)

Aritma IAM supports configuring external identity providers (IdPs) so your users can log in using their existing corporate credentials. Notably we generally support all OIDC SSO providers through "Custom" providers, other SSO mechanisms like SAML are not supported. Additionally we provide templates for more common providers like AzureAd and Signicat.

## Supported provider types

| Type | Description |
|  --- | --- |
| `Custom (Oidc)` | Any OpenID Connect-compliant identity provider |
| `AzureAd` | Microsoft Entra ID (Azure Active Directory) |
| `Google` | Google OAuth |
| `Signicat` | Signicat OAuth |


## How SSO works

1. You register an identity provider in Aritma IAM with a unique **scheme name**
2. The provider appears as a login option on the Aritma ID login page
3. When a user logs in via the SSO provider, Aritma ID authenticates them through the external IdP
4. Optionally, users can be **auto-provisioned** - a new Aritma subject is created the first time they log in


## Configuration

Each provider type requires a different set of properties. The full JSON schema for each provider type is documented in the [API Reference](/apis/platform/iam/openapi/iam-openapi#tag/SSO).

### Common provider properties

All provider types share these base configuration fields:

| Field | Description |
|  --- | --- |
| `scheme` | A unique identifier for this provider (used in login URLs) |
| `displayName` | The name shown on the login button |
| `clientId` | The OAuth 2.0 client ID registered with the identity provider |
| `clientSecret` | The OAuth 2.0 client secret. Leave `null` for public clients using PKCE |
| `loginEnabled` | Whether users can log in using this provider |
| `visible` | Whether this provider appears as a button on the login page |
| `autoProvisioningEnabled` | If `true`, users are automatically created in Aritma on first login |
| `delegationEnabled` | If `true`, tokens from this IdP can be used to call Aritma APIs directly |


### Azure AD / Microsoft Entra ID

Register an app in your [Azure portal](https://portal.azure.com) and obtain a client ID and secret. Then create the provider:

| Field | Description |
|  --- | --- |
| `authority` | Your Azure AD tenant endpoint, e.g. `https://login.microsoftonline.com/{tenant-id}/v2.0` |


### OpenID Connect (Custom)

Use this for any OIDC-compliant identity provider not covered by the templates above.

The `authority` must point to an OpenID Connect server. Aritma automatically fetches the `.well-known/openid-configuration` from this URL.

| Field | Description |
|  --- | --- |
| `authority` | The OIDC authority URL of the provider |
| `scope` | The OAuth 2.0 scopes to request (space-separated), e.g. `openid profile email` |
| `responseType` | The OAuth 2.0 response type: `code`, `id_token`, `token`, or `none` |
| `usePkce` | Whether to use PKCE for the authorization code flow |
| `getClaimsFromUserInfoEndpoint` | If `true`, fetches additional claims from the userinfo endpoint after authentication |
| `nameClaimType` | The claim type used to extract the user's name, e.g. `name` |
| `emailClaimType` | The claim type used to extract the user's email, e.g. `email` |
| `phoneNumberClaimType` | The claim type used to extract the user's phone number, e.g. `phone` |
| `subjectClaimType` | The claim type used as the subject identifier, e.g. `sub` |
| `verifyEnabled` | Whether this provider can be used to verify the user at a higher assurance level |


### Google

| Field | Description |
|  --- | --- |
| `authority` | The Google authority URL — typically `https://accounts.google.com` |
| `scope` | The OAuth 2.0 scopes to request, e.g. `openid profile email` |
| `usePkce` | Whether to use PKCE for the authorization code flow |
| `nameClaimType` | The claim type used to extract the user's name |
| `emailClaimType` | The claim type used to extract the user's email |
| `phoneNumberClaimType` | The claim type used to extract the user's phone number |
| `subjectClaimType` | The claim type used as the subject identifier |


### Signicat

Signicat is a Nordic eID provider supporting strong authentication methods such as BankID.

| Field | Description |
|  --- | --- |
| `authority` | The Signicat authority URL for your environment, e.g. `https://yourorg.signicat.com/auth/open` |
| `method` | The electronic ID method to enforce. One of: `None`, `BankId`, `MitId`, `SBID` |
| `verifyEnabled` | Whether to verify user identity on each login |


## Manage providers

### List providers

### Get a provider

Each provider type has its own get endpoint. Use the one matching the provider type:

### Update a provider

Send a `PUT` request with the same schema as the create request, including the provider `id`:

### Delete a provider

## Auto-provisioning

When `autoProvisioningEnabled` is `true`, the first time a user signs in via an SSO provider, Aritma automatically creates a user subject for them. This means you do not need to pre-invite users before they can log in.

## SCIM

Combine SSO with [SCIM Provisioning](/apis/platform/iam/scim/overview) if you want to also control which users exist on your tenant what groups they belong to from your identity provider.

## Custom provider icon

For `Custom` type providers, you can upload a custom icon to display on the login button:

To remove the icon: