> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anny.co/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth2 / OpenID Connect SSO

> Set up a company login via OAuth2 or OpenID Connect in anny, including callback URL, scopes, and attribute mapping.

In this article, you learn how to set up a company login via OAuth2 or OpenID Connect in anny. This is the right choice if your identity provider does not support SAML or you prefer OAuth2.

<Info>
  If your identity provider supports SAML 2.0, we recommend that path, as more features such as SCIM and federated logins are available. You find a guide under [Generic SAML 2.0 SSO](/en/generic-saml-sso).
</Info>

## Preparation

You can set up the SSO connection yourself in your anny [admin area](https://app.anny.co/organization/settings/sso?o=) under SSO & Security. Besides anny admin rights, you need administrative access to your identity provider to create an OAuth2 application there.

First, create a new OAuth2 application (sometimes also called "client" or "app") in your identity provider. In doing so, you receive a client ID and a client secret.

## Setup

<Steps>
  <Step title="Create the identity provider in anny">
    Go to the [SSO settings](https://app.anny.co/organization/settings/sso?o=), select "Add IDP" and then choose "Custom OAuth2" as the provider. Enter a name, for example "Company login".
  </Step>

  <Step title="Enter credentials and URLs">
    Enter the client ID, client secret, and the three endpoints of your identity provider. The table below explains which values are meant. Then save.
  </Step>

  <Step title="Add the callback URL to your identity provider">
    After saving, anny shows you the callback URL. Copy it and enter it in your identity provider as an allowed redirect URL.
  </Step>

  <Step title="Test the connection and activate it">
    Activate the identity provider via the three dots > Activate and test the login via "Test Connection".
  </Step>
</Steps>

<Warning>
  **Important:** The callback URL is only available after the first save, since it contains the ID of the identity provider. As long as the URL is not stored in your identity provider, the login fails with an error such as "redirect\_uri mismatch".
</Warning>

The callback URL follows this pattern, where `{id}` is the ID of the identity provider you created:

Callback URL: [**https://auth.anny.co/identity-provider/\{id}/oauth/callback**](https://auth.anny.co/identity-provider/\{id}/oauth/callback)

## Required fields

| Field in anny         | Description                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| **Client ID**         | The identifier of the OAuth2 application you created in your identity provider.                      |
| **Client Secret**     | The corresponding secret. anny stores it encrypted.                                                  |
| **Authorization URL** | The endpoint anny redirects your users to for the login. Often ends in `/authorize`.                 |
| **Token URL**         | The endpoint anny uses to retrieve the access token. Often ends in `/token`.                         |
| **User Info URL**     | The endpoint anny uses to retrieve the user data. Often ends in `/userinfo`.                         |
| **Scopes**            | The requested permissions, separated by spaces. With OpenID Connect, usually `openid profile email`. |

<Tip>
  Many identity providers publish their endpoints under `https://<your-provider>/.well-known/openid-configuration`. There you find the values for authorization URL, token URL, and user info URL bundled together.
</Tip>

## Advanced options

You only need the advanced options if your identity provider deviates from the standard. You find them in the form under "Advanced options".

| Field in anny                        | Description                                                                                             |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| **Use PKCE**                         | Enable this option if your identity provider requires Proof Key for Code Exchange.                      |
| **Scope separator**                  | Character used to separate the scopes in the request. Most OpenID Connect providers expect a space.     |
| **Send token request as JSON**       | Requests the access token with a JSON body instead of form encoding.                                    |
| **Basic auth username and password** | Are sent as HTTP Basic authentication to the token endpoint, if your identity provider requires it.     |
| **Attribute fields**                 | Define which fields of the user info response anny reads the ID, email, first name, and last name from. |

### Mapping attributes

By default, anny expects the fields `id`, `email`, `firstname`, and `lastname`. Many identity providers use different names. With OpenID Connect, the following values are common, for example:

| Field in anny            | Typical value with OpenID Connect |
| ------------------------ | --------------------------------- |
| **User ID attribute**    | `sub`                             |
| **Email attribute**      | `email`                           |
| **First name attribute** | `given_name`                      |
| **Last name attribute**  | `family_name`                     |

If the values are nested in the response, you can specify the path with dots, for example `data.user.id`.

<Note>
  These fields only control where anny reads the user data from. If you additionally want to assign users to communities automatically, use [attribute mapping](/en/attribute-mapping) for that.
</Note>

## After the setup

* Via the three dots, you can generate a wayfless link. With it, your users land directly in the login of your identity provider.
* With [attribute mapping](/en/attribute-mapping), you automatically assign users to communities.

## Troubleshooting

<AccordionGroup>
  <Accordion title="404: Page not found">
    The identity provider is not activated yet. Activate it via the three dots > Activate. As long as it is deactivated, login and callback are intentionally not reachable.
  </Accordion>

  <Accordion title="redirect_uri mismatch">
    The callback URL is not stored in your identity provider, or not exactly. Copy it from anny again and make sure it matches character for character, including `https://` and without a trailing slash.
  </Accordion>

  <Accordion title="Login works, but user data is missing">
    Check the attribute fields in the advanced options. If your identity provider returns `given_name` instead of `firstname`, for example, the value has to be entered there accordingly. Also check whether the requested scopes are sufficient to receive email and names.
  </Accordion>

  <Accordion title="Error when retrieving the token">
    Check the client ID and client secret as well as the token URL. If your identity provider requires HTTP Basic authentication or a JSON body, enable the matching advanced options.
  </Accordion>
</AccordionGroup>

You find a general overview of SSO here: [SSO Overview](/en/sso-overview)