Login.gov supports integration with federal and state agency applications using standard authentication protocols. This article covers how to get started with an integration, the tools available, supported platforms, reporting, and common technical questions.

 

Getting Started

Integration with Login.gov follows these high-level steps:

1. Create a sandbox account using a .gov or .mil email address at the sandbox Partner Portal. No agreement is required for sandbox testing.
2. Register your application in the sandbox Partner Portal and configure it.
3. Build and test your integration using the Login.gov developer documentation.
4. Request production deployment when ready. The deployment process can take up to two weeks. See production deployment instructions.

Login.gov recommends OpenID Connect (OIDC) protocols whenever possible, but supports SAML as well. Detailed setup instructions are in the developer documentation.

Login.gov’s Onboarding Engineering team is available to help with technical issues before, during, and after launch. Submit support requests through the Partner Support Help Desk.

Supported Platforms

Login.gov works with any platform that supports OIDC or SAML. Common platforms partners have integrated with include:

• Okta — setup instructions
• Ping Identity
• ForgeRock
• Oracle AM
• Microsoft Dynamics 365
• Microsoft ADFS
• Salesforce
• ServiceNow
• Amazon Cognito — setup instructions
• Keycloak
• Shibboleth
• Azure AD B2C — setup instructions
• OAuth2 Proxy — setup instructions

Authorization

Login.gov provides authentication and identity verification services. It does not provide authorization. Partners handle authorization — assigning roles, permissions, and access levels — on their side after receiving user attributes from Login.gov.

Sandbox Environment

The sandbox environment is available for testing integrations without affecting production. Key details:

• Supported Monday–Friday, 8am–5pm ET
• Sandbox and production accounts are separate
• Users with .gov or .mil email addresses can create sandbox accounts directly
• Government contractors need an agency partner to add them to a team in the sandbox Partner Portal
• Due to spam issues, sandbox accounts cannot be created with aol.com, bellsouth.net, outlook.com, or yahoo.com email addresses (this does not apply to production)
• Login.gov does not support automatic or bulk creation of test users in any environment

User Attributes

Login.gov returns user attributes based on the identity assurance level configured for your application. Available attributes and how to request them are documented in the developer documentation.

Email Handling

Login.gov allows users to associate multiple email addresses with their account and set a preferred email per connected application.

• By default, the “email” attribute returns the user’s preferred email for your application, or the last email they signed in with.
• If your application requests the “all_emails” attribute, you receive all email addresses on the account. This disables the preferred email feature.
• Recommendation: Track users by their UUID rather than email address, since email addresses can change. Use email for initial account linking, then store the UUID for subsequent lookups.

Microsoft Power Pages

Microsoft Power Pages does not appear to support specifying a user attribute other than email address for account linking. If users sign in with multiple email addresses, Power Pages may create separate accounts. Consider requesting the “all_emails” attribute to check for existing accounts.

Session and Browser Behavior

Login.gov sessions expire after 15 minutes of inactivity. Login.gov does not end sessions when a user closes a browser tab. This is an intentional design choice based on NIST session management guidance that balances security with user experience.

Partners concerned about shared-computer scenarios should implement their own session timeout matching Login.gov’s 15-minute window. For details on session behavior across different scenarios, see the [Authentication guide].

Logout Behavior

• OIDC integrations: When a user logs out of a partner application, they can be prompted to also log out of Login.gov.
• SAML integrations: Logout signs the user out of both the partner application and Login.gov.

Login.gov recommends OIDC over SAML partly because it gives users the choice to remain signed in to Login.gov when logging out of a specific application.

IALMAX Depreciation

Login.gov no longer supports IALMAX for new integrations. It is a non-standard IAL that is difficult to maintain. Partners needing alternatives should contact Partner Support.

Load Testing

Login.gov does not currently support partners conducting load tests against the Login.gov environment due to the cost and complexity of matching production capacity in sandbox.

Login.gov’s platform is built with elastic components on AWS and handles millions of sign-ins per month. 

If you need load assurance, share your expected targets (number of users, activity type, timeframe, and rollout plan) so Login.gov can map internal test results to your requirements.

Change Management

When transitioning your application to Login.gov, the following resources help prepare your team and users:

• User experience guide: Covers integration decisions that affect user experience, including preparing customer support materials.
• FAQ content: Recommended language for communicating with your user base about Login.gov.
• Login.gov’s contact center handles sign-in issues 24/7. Account linking issues are typically handled by the partner agency.

Enforcing .gov Email Addresses

Login.gov does not restrict account creation to .gov email addresses. If your application requires a .gov email, enforce this on your side by checking the “all_emails” attribute returned by Login.gov.

Decommissioning An Application

To retire an application from Login.gov, submit a decommission request through the Partner Support Help Desk.

Maintenance and Downtime Notification

If your application has scheduled maintenance or downtime, add the following email to your notification mailing list so the Login.gov team and contact center are aware:

login-sp-service-noti-aaaaiu5zlbcvkrxlrkem4qfl2a@gsa.org.slack.com

Common Developer Challenges

Partners familiar with OIDC or SAML typically have little trouble integrating with Login.gov. The most common challenges arise when:

• Using a third-party platform that doesn’t work well with Login.gov’s requirements
• The person implementing the integration is not a technical developer

The developer documentation is designed to be thorough and self-service. If anything is unclear, submit feedback so Login.gov can improve it.