# Okta SAML single sign-on

<!-- Generated by scripts/generate.ts. Do not edit. -->

Create a SAML 2.0 app integration in Okta, paste the values from this setup, assign your users and share the app's metadata with us.

:::caution[Verification]
Not yet verified on a real Okta tenant. It was written from the public Okta documentation, so labels in the admin console may differ slightly.
:::

The values in braces, such as `{acs_url}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="create-app"></a>

### Create a SAML app integration

In the Okta Admin Console, go to Applications and Resources > Applications, select Create App Integration, choose SAML 2.0 as the sign-in method and select Next. Give the app a name your users will recognize and select Next.

</li>

<li class="idp-step">

<a id="acs"></a>

### Enter the single sign-on URL

In Single sign-on URL, paste `{acs_url}`. Keep "Use this for Recipient URL and Destination URL" selected.

<div class="setup-values">

Paste into Okta:

- ACS URL: `{acs_url}`

</div>

Fixes: [`saml_destination_mismatch`](/errors/saml_destination_mismatch/), [`saml_response_malformed`](/errors/saml_response_malformed/)

</li>

<li class="idp-step">

<a id="audience"></a>

### Enter the audience URI

In Audience URI (SP Entity ID), paste `{sp_entity_id}`.

<div class="setup-values">

Paste into Okta:

- SP entity ID: `{sp_entity_id}`

</div>

Fixes: [`saml_audience_mismatch`](/errors/saml_audience_mismatch/)

</li>

<li class="idp-step">

<a id="name-id"></a>

### Send the email address as the name ID

Set Name ID format to EmailAddress and Application username format to Email.

Fixes: [`saml_nameid_missing`](/errors/saml_nameid_missing/)

</li>

<li class="idp-step">

<a id="signing"></a>

### Check the signing settings

Under Show Advanced Settings, keep Response and Assertion Signature set to Signed and Signature Algorithm set to RSA-SHA256.

Fixes: [`saml_signature_missing`](/errors/saml_signature_missing/), [`saml_signature_algorithm_weak`](/errors/saml_signature_algorithm_weak/)

</li>

<li class="idp-step">

<a id="attributes"></a>

### Add the attribute statements

Under Attribute Statements, add email mapped to user.email, firstName mapped to user.firstName and lastName mapped to user.lastName. To send groups, add a group attribute statement named groups.

Fixes: [`saml_email_missing`](/errors/saml_email_missing/)

</li>

<li class="idp-step">

<a id="finish"></a>

### Finish creating the app

Select Next, choose "I'm an Okta customer adding an internal app" and select Finish.

</li>

<li class="idp-step">

<a id="assign"></a>

### Assign people to the app

On the app's Assignments tab, assign the people or groups who should sign in with single sign-on.

Fixes: [`saml_idp_status_error`](/errors/saml_idp_status_error/)

</li>

<li class="idp-step">

<a id="metadata"></a>

### Share the identity provider metadata

On the app's Sign On tab, copy the metadata URL (or download the metadata file) and add it to this setup. Do this again whenever the signing certificate changes.

Fixes: [`saml_signature_invalid`](/errors/saml_signature_invalid/), [`saml_issuer_mismatch`](/errors/saml_issuer_mismatch/)

:::caution[Labels not confirmed in step 9]
The public Okta pages read on 2026-10-11 do not say where the metadata link sits on the Sign On tab.
:::

</li>

<li class="idp-step">

<a id="test"></a>

### Test the connection

Run a test sign-in in this setup, signing in as a user you assigned to the app.

</li>

</ol>

<a id="standby"></a>

## Optional: add the standby ACS URL

If our main network ever has an outage, sign-ins can continue through a standby address, but only if Okta accepts it. In the app's SAML settings, under Show Advanced Settings, turn on "Other Requestable SSO URLs" and add `{standby_acs_url}` with index 1. Then confirm in this setup that you added it.

<div class="setup-values">

Paste into Okta:

- Standby ACS URL: `{standby_acs_url}`

</div>

This step is optional. See [standby route behavior](/trust/standby/) for what the standby address does during an outage.

## Sources

- [Create SAML app integrations (Okta Help)](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm), read on 2026-10-11
- [Application Integration Wizard SAML field reference (Okta Help)](https://help.okta.com/en-us/content/topics/apps/aiw-saml-reference.htm), read on 2026-10-11
