SAML developer guide | Login.gov (2024)

We strongly recommend choosing OpenID Connect (OIDC) over SAML due to its modern, API-centric design and support for native mobile applications.

Getting started

SAML is an established standard, but can be a bit complex. We recommend looking for and using a SAML library for your language before developing your own.

Configuration

Here are values needed to configure your service provider (SP) to work with Login.gov:

NameID Format

The NameID is the unique identifier used to identify a user across multiple sessions. The format is the standard v4 random UUID (Universally Unique Identifier) in compliance with RFC 4122. For example:
<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>

Login service URL and Binding

This is the endpoint where authentication requests are sent to Login.gov (aka Single Sign-on Service). For example:
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.int.identitysandbox.gov/api/saml/auth2024"/>

Logout service URL and Binding

The single logout service URL is used to contact the Single logout profile (aka Single Logout Service). For example:
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.int.identitysandbox.gov/api/saml/logout2024" />

x509 Public Certificate

The public certificate is used to validate the authenticity of SAML requests received from Login.gov, a minimum of 2048 bits. We publish this public certificate from our metadata endpoint and below for verification.

Metadata

Consistent with the SAML metadata specification, Login.gov’s metadata for our sandbox environment is available at https://idp.int.identitysandbox.gov/api/saml/metadata2024.

Signing Certificates

Below you can find the X509 certificates used by the Login.gov IdP to sign SAML requests. Do not enter these certificates in the Dashboard when configuring an application for testing - you can follow the instructions in our testing article to generate a client certificate.

-----BEGIN CERTIFICATE-----MIID7TCCAtWgAwIBAgIUYePi2i1UjRg3fIK0FG15rZaSOvAwDQYJKoZIhvcNAQELBQAwgYUxCzAJBgNVBAYTAlVTMR0wGwYDVQQIDBREaXN0cmljdCBvZiBDb2x1bWJpYTETMBEGA1UEBwwKV2FzaGluZ3RvbjEMMAoGA1UECgwDR1NBMRIwEAYDVQQLDAlMb2dpbi5nb3YxIDAeBgNVBAMMF2ludC5pZGVudGl0eXNhbmRib3guZ292MB4XDTI0MDExNjIwMTEyMloXDTI1MDQwMTIwMTEyMlowgYUxCzAJBgNVBAYTAlVTMR0wGwYDVQQIDBREaXN0cmljdCBvZiBDb2x1bWJpYTETMBEGA1UEBwwKV2FzaGluZ3RvbjEMMAoGA1UECgwDR1NBMRIwEAYDVQQLDAlMb2dpbi5nb3YxIDAeBgNVBAMMF2ludC5pZGVudGl0eXNhbmRib3guZ292MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0K9gJdCDRwndI+Gd44cugWK3VWKgPV/oZU74KqYxJOomJUgLLYMHskS3RDlOla+k25SvBLWFlT9Y10RAnWo6ZDquY+/BaedyoTaoLf/5K/JxXz8th00aIll4ym3CLE/ac9B7s/apACdpH63XwAlaRC3A4Hbq1DWXd2Hcuw0B9pRpMKFd6i/kVvAsNH7tNn5gBL9hckiPxR4FD8/VysnVmXpNNFyKNEUQi6iqKVbUhzB+4WZMB/qBnnIEeSuUpHfQCUJR3SjRYzBLR+iVAXKeNCg7CENZbu02AY32kyO6QStQnGItTi355p4VFumA4dQS2MZsXYAPo+QP+qe6rguXaQIDAQABo1MwUTAdBgNVHQ4EFgQUGbZYf4tPIbZxRYwemr7iRXcS8jUwHwYDVR0jBBgwFoAUGbZYf4tPIbZxRYwemr7iRXcS8jUwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAtPlcy1eToYc2B0+zg4DdGQDZQA897Z7oLX0nfpf4Bsx1sQzqhEd1iBPh4/g0wO45T4c0aOdH+bdv8UC9NWupKdIrz9VGY3XD5ef8ydTWAzcN9k+gTZmPQ506SRqI6GlWy8QDuPX+sK7apOkd/TUILAeoA9on+v8qg52jU1E4e8La8Kd8PPNWbAbLew2lp/ANRYbtcPmVbJYOlY8nBOZadzL3LPwWkPJII78hmSc2eV4UqyTVbJ/k15i+tx+8GALx1LHMri11fvcFhJUx/qfGU6X7xnI32eZtmOH7Y+Xi9dxh560ohSgP3m4xv2YKsVjm2tPZGfZvpOGNEYTvdaXaAA==-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----MIIDzzCCAregAwIBAgIUBedAGri4qfIqwYynVBmUJ598viAwDQYJKoZIhvcNAQELBQAwdzELMAkGA1UEBhMCVVMxHTAbBgNVBAgMFERpc3RyaWN0IG9mIENvbHVtYmlhMRMwEQYDVQQHDApXYXNoaW5ndG9uMQwwCgYDVQQKDANHU0ExEjAQBgNVBAsMCUxvZ2luLmdvdjESMBAGA1UEAwwJbG9naW4uZ292MB4XDTI0MDExNjIwMTE1MloXDTI1MDQwMTIwMTE1MlowdzELMAkGA1UEBhMCVVMxHTAbBgNVBAgMFERpc3RyaWN0IG9mIENvbHVtYmlhMRMwEQYDVQQHDApXYXNoaW5ndG9uMQwwCgYDVQQKDANHU0ExEjAQBgNVBAsMCUxvZ2luLmdvdjESMBAGA1UEAwwJbG9naW4uZ292MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuhtUVOX/nhTLLAb3dc2AMuPfUN8TtqxCaXGdwdDbY76nL1oTkrk3zns95OlC0+gg8EhuRpxii6snxa/JDZPHQuAGWBS5KWcD/pNxP7TIghrqPtPGPuK2EM3tduYObN3VEMhpfa*gtP+wQQ/n16i4wbTeRHm4O5T8vWTUeZqxP/l9ja/txexv+LLmeR+zI9k51OfwWzr25HW1j6AkRTB/BQgt9Z29h7QNiGUiYQNBgXf3E03oOo8UCl7JXRLxygaBT67nOrFK9gxxs4nHVfhbrnA8VoUm+CrDczP46nAnXKk0HoQWFOlJDKNowbm3fHGt8CkLJBOszI+Hz0b7nQ8sFRQIDAQABo1MwUTAdBgNVHQ4EFgQUon3wLMwFr2s3AdO9u2vcGnhoH5wwHwYDVR0jBBgwFoAUon3wLMwFr2s3AdO9u2vcGnhoH5wwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAp6N3nT6GNkjMiEfsvwp66QDF2Fbjaelh6eRMf/QUwEttWawRB9IMnBzL0EOxZQ8jm3V1n8mev7fFJbP/bDnqsnhag+0cPGtQjVl5ZAImjmfIu0gvOrvZqoiAKi6WHDD8UAd/XNr4Eui9DHRKx9QBABajDwyfgWBE7phc5zosEyxep8n+pytxcWDAbR2kzKVac1+mXPwXSLN4ORh7TI9kzipojBlQWMG0Hx+VU+FjX5+pMqIpME5KAhj1yZdDk7/ji4apPwsrQ5BBXQd9w1T7I7ONK0+uVCGgJDDBnmA7HfoJjG4LL9lBgb1U/adQMcTTfASiTYMiQCZX/hZNyfUF1g==-----END CERTIFICATE-----

Annual Certificate Rotation

The Login.gov SAML certificate is valid for just over one year. Every spring, Login.gov adds new SAML endpoints with the current year that use a new signing certificate.

  • /api/saml/auth2023 becomes /api/saml/auth2024
  • /api/saml/logout2023 becomes /api/saml/logout2024

The certificates are issued to create an overlap period of about a month, during which all partners using SAML should migrate at their convenience to the new endpoint URLs for the current year.

The 2023 certificates for idp.int.identitysandbox.gov and secure.login.gov each expire on April 1, 2024. So the transition from 2023 to 2024 endpoints should take place in February or March 2024.

Example application

The Login.gov team has created an example client to speed up your development, all open source in the public domain: identity-saml-sinatra.

Next step: Authentication

Edit this page

SAML developer guide | Login.gov (2024)

FAQs

How to fix SAML response error? ›

Solution
  1. Go to Authentication > Enterprise.
  2. Click SAML.
  3. Click on the connection you want to check.
  4. On the Setup tab, under the Common Settings section, your Entity ID is the second parameter provided. Make sure that the identity provider sends the correct audience value in the SAML response.

Is login.gov FedRAMP? ›

Login.gov is a FedRAMP moderate approved multifactor authentication and identity proofing platform that makes online interactions with the U.S. government simple, efficient and intuitive.

How do I read SAML responses in Chrome? ›

Google Chrome
  1. Press F12 to start the developer console.
  2. Select the Network tab, and then select Preserve log.
  3. Reproduce the issue.
  4. Look for a SAML Post in the developer console pane. Select that row, and then view the Headers tab at the bottom. Look for the SAMLResponse attribute that contains the encoded request.

How does SAML enable logins? ›

SAML uses a claims-based authentication workflow. First, when a user tries to access a site, the service provider asks the identity provider to authenticate the user. Then, the service provider uses the SAML assertion issued by the identity provider to grant the user access.

What is error occurred while processing the SAML response? ›

This error means that the Service Provider (SP) wasn't able to decrypt the assertion created by the Identity Provider (IdP), which causes the authentication process to fail. Thus, the certificate configuration might haven't been performed correctly.

Is SAML obsolete? ›

Like OIDC, the SAML protocol is not obsolete. Various industries (such as healthcare and education) use it to securely authenticate users by enabling secure exchanges of assertions about a user's identity between an identity provider and a service provider.

Is Login.gov used by IRS? ›

Taxpayers as of July 14 are required to sign in or register with either of the IRS' credential service providers, Login.gov or ID.me, to access the FATCA Registration System.

Is Login.gov a real government site? ›

Is Login.gov a federal agency? Login.gov is not a standalone federal agency. We are a program of the General Services Administration (GSA), an agency of the U.S. federal government.

Does Login.gov use facial recognition? ›

Login. gov's facial matching capability uses a privacy-preserving approach that compares 'selfies' exclusively with the user's photo ID, and does not use the image for any other purpose,” Davis says.

How to check if SAML is working? ›

To view a SAML response in Chrome

Press F12 to start the developer console. Select the Network tab, and then select Preserve log. Reproduce the issue. Look for a login entry in the developer console pane.

How to find SAML response? ›

Manual Approach:
  1. Open the developer tools. ...
  2. Select the Network tab, and then select Preserve log.
  3. Reproduce the SAML issue.
  4. Look for a SAML Post with a samlconsumer call in the developer console pane.
  5. Select that row, and then view the Headers tab at the bottom.
May 5, 2021

What is the difference between SAML response and SAML assertion? ›

A SAML Response is a reaction of the IdP to SURFconext with the message that the user has been successfully authenticated (or not). A SAML Assertion is some statements done by IdP or SP: authentication, authorization and attributes.

Is SAML better than OAuth? ›

While both can be used for SSO, they are not interchangeable or mutually exclusive. SAML supports both user authentication and authorization while OAuth is only for authorization. If the business priority is confirming user identity, SAML is the only choice.

What is the difference between SAML and SSO? ›

Security Assertion Mark-up Language (SAML) is an authentication standard that allows for federated identity management and can support single sign-on (SSO). SSO is an authentication scheme that allows a user to log in with a single ID and password to any independent or federated software systems.

How do I check if a user is logged in SAML? ›

To check if a user is logged or not you should load the simpleSAMLphp library and then use the function isAuthenticated().

How to fix error 403 SAML error? ›

To resolve the 403 app_not_enabled_for_user error:
  1. Sign in to your Google Admin console. ...
  2. In the Admin console, go to Menu Apps. ...
  3. In the app list, locate the SAML app generating the error.
  4. Click the app to open its Settings page.
  5. Click User access.
  6. Turn the app ON for everyone or for the user's organization.

How do you fix an SSO error? ›

General troubleshooting
  1. In your IdP: Confirm that your Org ID, Entity ID, and ACS URL are all correct. Review the SAML attribute statements that you've entered. Regenerate the SAML metadata and replace it in Iterable.
  2. In Iterable: Check the SAML Domain field. Learn how. Replace the SAML metadata from your IdP.

How can you troubleshoot the SAML workflow if there are any issues? ›

Check if idp do not have assertion signed. Ask idp team that response is signed, and the assertion needs to be signed as per saml spec. Check if SAML tracer output if the assertion from IDP is encrypted. If yes, Config of SAML auth handler should use the encryption checkbox.

What is an error occurred in the SAML authentication flow? ›

SAML errors usually occur when there's missing or incorrect information entered during your SAML setup. You can resolve most of these issues from your IDP settings, but for some, you'll need to update your SSO settings in Slack as well.

References

Top Articles
Latest Posts
Article information

Author: Fredrick Kertzmann

Last Updated:

Views: 6246

Rating: 4.6 / 5 (66 voted)

Reviews: 81% of readers found this page helpful

Author information

Name: Fredrick Kertzmann

Birthday: 2000-04-29

Address: Apt. 203 613 Huels Gateway, Ralphtown, LA 40204

Phone: +2135150832870

Job: Regional Design Producer

Hobby: Nordic skating, Lacemaking, Mountain biking, Rowing, Gardening, Water sports, role-playing games

Introduction: My name is Fredrick Kertzmann, I am a gleaming, encouraging, inexpensive, thankful, tender, quaint, precious person who loves writing and wants to share my knowledge and understanding with you.