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/auth2023becomes/api/saml/auth2024/api/saml/logout2023becomes/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.
