# Single Sign-On (SSO) The Aktify Portal supports Single Sign-On through **SAML 2.0** and **OpenID Connect (OIDC)**. Once connected, your users sign in with your company's existing identity provider — Okta, Microsoft Entra ID (Azure AD), Google Workspace, Auth0, OneLogin, and others — instead of a separate Aktify password. You configure SSO yourself in the Portal. No Aktify engineering work is required once your company's account has been set up. ## How it works Every Aktify customer has its own isolated login directory, tied to your company's **email domain** (for example, `yourcompany.com`). When someone signs in, the Portal looks at the domain of the email they enter, finds your company, and shows the sign-in options you've enabled. When you connect an identity provider: 1. The Portal shows a **Sign in with <your provider name>** button to anyone who enters an email at your domain. 2. Clicking it sends the user to your identity provider to authenticate. 3. Your identity provider sends the user back to Aktify with a signed assertion (SAML) or token (OIDC) containing their email and name. 4. Aktify creates the user's Portal account on first sign-in and signs them in. Password sign-in remains available alongside SSO. Users who already have an Aktify password can keep using it, and SSO users never need one. :::info SSO does not assign roles SSO handles **authentication** (proving who someone is), not **authorization** (what they can do). A user who signs in through SSO for the first time has no role and sees a **No Permissions Assigned** screen until an Admin grants them one. See [Step 4](#step-4--grant-roles-to-your-users). ::: ## Before you begin You'll need: - An Aktify Portal account with the **Admin** role. Only Admins can see the SSO settings. - Admin access to your identity provider, so you can create an application and read its metadata. - Your company's login to be set up by Aktify. If your users see *"There is no account for this email"* on the login page, contact your Aktify Account Manager — your company's email domain hasn't been registered yet. Decide which protocol to use. If your identity provider offers both, **SAML** is the more common choice for workforce SSO and needs no client secret. Use **OIDC** if your provider only supports OpenID Connect or you prefer it. ## Step 1 — Get Aktify's connection details 1. Sign in to the [Aktify Portal](https://admin.aktify.io) as an Admin. 2. Open **Settings** from the main navigation and select the **Organization** tab. 3. Choose **SAML** or **OIDC**. 4. Under **SAML Settings** (or **OIDC Settings**), click the **Add new** (**+**) button. The top of the dialog, titled **Aktify's SAML Details** or **Aktify's OIDC Details**, lists the values your identity provider will ask for. Each has a copy button. Keep this dialog open while you complete Step 2 in another tab. ### SAML values | Portal label | What your identity provider calls it | | :--- | :--- | | **Authorized JavaScript Origins** | Trusted origin / allowed origin | | **Authorized Redirect URI / Single Sign On URL** | ACS URL, Reply URL, Single sign-on URL, or Assertion Consumer Service URL. It ends in `/saml2/idpresponse`. | | **Audience** | Audience URI, Entity ID, SP Entity ID, or Identifier. It looks like `urn:amazon:cognito:sp:`. | ### OIDC values | Portal label | What your identity provider calls it | | :--- | :--- | | **Authorized JavaScript Origins** | Trusted origin / allowed origin | | **Authorized Redirect URI** | Redirect URI, Callback URL, or Sign-in redirect URI. It ends in `/oauth2/idpresponse`. | ## Step 2 — Create an application in your identity provider In your identity provider's admin console, create a new **SAML** or **OIDC / OAuth 2.0 web** application for Aktify and paste in the values from Step 1. The exact screens vary by provider, but every provider needs the same information. ### SAML 1. Create a new SAML 2.0 application (Okta: *Applications → Create App Integration → SAML 2.0*; Entra ID: *Enterprise applications → New application → Create your own → Integrate any other application*). 2. Set the **Single sign-on URL / ACS URL / Reply URL** to Aktify's **Authorized Redirect URI / Single Sign On URL**. 3. Set the **Audience URI / Identifier (Entity ID)** to Aktify's **Audience**. 4. Set **Name ID format** to email address if your provider asks. Aktify identifies users by their email attribute, so the Name ID format itself doesn't need to be exact. 5. Add attribute statements (claims) for at least the user's **email**. Adding **first name**, **last name**, and/or **full name** is optional but recommended so names appear correctly in the Portal. Note the exact attribute names your provider sends — you'll enter them in Step 3. 6. Assign the users or groups who should be able to access the Portal. 7. Copy the application's **metadata URL** (sometimes called *Identity Provider metadata* or *App Federation Metadata Url*). If your provider only offers a downloadable metadata XML file, download it instead. ### OIDC 1. Create a new **OIDC / OAuth 2.0 web application**. 2. Set the **Sign-in redirect URI / Callback URL** to Aktify's **Authorized Redirect URI**. 3. Enable the **Authorization Code** grant type. 4. Assign the users or groups who should be able to access the Portal. 5. Copy the application's **Client ID**, **Client secret**, and **Issuer URL** (also called the *authority* or *OpenID Connect metadata* base URL — the URL that serves `/.well-known/openid-configuration`). ## Step 3 — Connect the provider in the Portal Return to the dialog you opened in Step 1 and fill in **Your SAML Details** or **Your OIDC Details**. ### Name The **Name** is shown to your users on the Aktify login button as **Sign in with <Name>**, so pick something they'll recognize — for example `Okta`, `Microsoft`, or `YourCompany-SSO`. Use letters, numbers, dashes, and underscores only; spaces aren't allowed. :::warning Choose the name carefully The name can't be changed after the provider is created. Deleting and recreating a provider under a different name **disconnects every user** who signed in through it (see [Deleting a provider](#deleting-a-provider)). `Google` is a reserved name and can't be used. ::: ### SAML fields | Field | What to enter | | :--- | :--- | | **Metadata by URL** / **Metadata by XML** | Choose how you'll supply your provider's metadata. URL is preferred: Aktify can pick up certificate rotations automatically. | | **Metadata URL** | The metadata URL from Step 2. Examples: `https://yourcompany.okta.com/app//sso/saml/metadata`, `https://login.microsoftonline.com//federationmetadata/2007-06/federationmetadata.xml?appid=`, `https://yourcompany.us.auth0.com/samlp/metadata/`. | | **Metadata XML** | The full contents of the downloaded metadata file, if you chose XML. | | **Email attribute** | **Required.** The attribute name your provider uses for the user's email. This may be short (`email`) or a full claim URI such as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. | | **Full name attribute** | Optional. The attribute containing the user's display name, for example `name` or `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`. | | **First name attribute** | Optional. For example `firstName` or `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`. Used before the full name when present. | | **Last name attribute** | Optional. For example `lastName` or `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`. Used before the full name when present. | ### OIDC fields | Field | What to enter | | :--- | :--- | | **Client ID** | From your provider's application. | | **Client secret** | From your provider's application. | | **Authorized scopes** | Space-separated scopes to request. `openid email profile` covers everything Aktify uses. | | **Issuer** | The issuer URL from Step 2, for example `https://yourcompany.okta.com` or `https://login.microsoftonline.com//v2.0`. Aktify discovers the remaining endpoints from `/.well-known/openid-configuration`. | | **Attributes request method** | `GET` or `POST` — how Aktify calls your provider's user-info endpoint. `GET` works for nearly all providers. | | **Email attribute** | **Required.** The claim containing the user's email. Usually `email`. | | **Username attribute** | Optional. The claim to use as a stable username, for example `sub` or `preferred_username`. | | **Full name attribute** | Optional. Usually `name`. | | **First name attribute** | Optional. Usually `given_name`. | | **Last name attribute** | Optional. Usually `family_name`. | Click **Create**. The provider appears in the table under **SAML Settings** / **OIDC Settings** with its **Enabled** switch turned on. SSO is live for your users immediately. :::tip Test it right away Open a private browser window, go to the [login page](https://admin.aktify.io/login), enter your email, and confirm the **Sign in with <Name>** button appears and completes a round trip to your identity provider. Your existing Admin account keeps working with its password, so you can't lock yourself out by testing. ::: ## Step 4 — Grant roles to your users A user who signs in with SSO for the first time is created with **no role** and sees a **No Permissions Assigned** screen asking them to contact their IT team. To give them access: 1. Go to **Settings → Organization**. 2. Find the user in the user list. They appear as soon as they've completed their first SSO sign-in. 3. Assign a role — **Admin**, **Editor**, or **Read-Only**. See the [role definitions](../company-pages/settings#roles). The user can refresh the Portal and will have access immediately. :::note Roles aren't imported from your identity provider's groups. You control Portal access by choosing who can reach the Aktify application in your identity provider, and what they can do by assigning roles in the Portal. ::: ## Managing your provider All of these live under **Settings → Organization** and require the **Admin** role. ### Turning SSO off and on Use the **Enabled** switch in the provider's row. Turning it off removes the **Sign in with <Name>** button from the login page without deleting your configuration; turn it back on at any time. Password sign-in is unaffected either way. ### Editing a provider Click the **Edit** (pencil) action on the provider's row. You can update the metadata, client credentials, and attribute mappings. The **Name** is not editable. ### Deleting a provider Click the **Delete** (trash) action and confirm. :::warning Deleting a provider disconnects its users Portal users who signed in through the deleted provider stay in your user list but can no longer sign in. If you recreate the connection later with **exactly the same name**, those users reconnect automatically. If you use a different name, delete the orphaned users from the user list — they'll be recreated on their next SSO sign-in and will need roles assigned again. ::: ### One provider of each type The Portal supports one SAML provider and one OIDC provider per company. If you need more than one connection of the same type, contact your Aktify Account Manager. ## Troubleshooting | Symptom | What it usually means | | :--- | :--- | | The login page says *"There is no account for this email"* | The email domain isn't registered with Aktify, or the user typed a personal address. Users must use an email at your company's registered domain. If the domain is right, contact your Aktify Account Manager. | | The login page says *"...not quite ready for login"* | Aktify has registered your domain but hasn't finished provisioning the login. Contact your Aktify Account Manager. | | No **Sign in with <Name>** button appears | The provider's **Enabled** switch is off, or the user entered an email at a different domain. | | Redirected back to the login page with *"Error in SAML request to Identity Provider: No SAML assertion found"* | Your identity provider rejected the request before issuing an assertion. Most often the user isn't assigned to the Aktify application in your provider, or the **ACS URL** / **Audience** in your provider doesn't exactly match the values from Step 1. | | Error mentioning a missing or invalid `email` attribute | The **Email attribute** you entered in Step 3 doesn't match the attribute name your provider actually sends. Check the attribute statements / claims on the application and copy the name exactly, including any `http://schemas...` prefix. | | Signed in successfully but see **No Permissions Assigned** | Expected on first sign-in. An Admin must assign a role — see [Step 4](#step-4--grant-roles-to-your-users). | | Names appear blank or as an email address in the Portal | Add the optional name attributes in Step 3 and make sure your provider sends them. | | OIDC error about `redirect_uri` mismatch | The redirect URI registered in your provider doesn't exactly match Aktify's **Authorized Redirect URI**, including `https://` and the `/oauth2/idpresponse` path. | | OIDC error about an invalid client or issuer | Re-check the **Client ID**, **Client secret**, and **Issuer**. The issuer must be the base URL that serves `/.well-known/openid-configuration`, with no trailing slash. | If you're still stuck, contact your Aktify Account Manager with the provider name, the time of the failed attempt, and the exact error text shown on the login page.