20 | {% if item.properties %}
21 | {% include schema.html schema=item.properties %}
22 | {% endif %}
23 |
24 | {% endfor %}
25 |
--------------------------------------------------------------------------------
/_includes/search.html:
--------------------------------------------------------------------------------
1 |
2 |
30 |
--------------------------------------------------------------------------------
/_includes/snippets/auth_content/aal_values.md:
--------------------------------------------------------------------------------
1 | {% capture aal_values %}
2 | We default to requiring a user to be authenticated with a second factor:
3 | - **`urn:gov:gsa:ac:classes:sp:PasswordProtectedTransport:duo`**
4 | This specifies that a user has been authenticated with a second factor. This value will be returned in the user attributes by default. We do not allow strict AAL1, because it implies that a user did not authenticate with a second factor. This setting requires users to reauthenticate with a separate second factor (i.e. not a remembered device) once every 30 days at a minimum.
5 |
6 | Stricter behavior can be specified by adding one of:
7 |
8 | - **`http://idmanagement.gov/ns/assurance/aal/2`**
9 | This is the same as the default behavior except users must authenticate with a separate second factor (i.e. not a remembered device).
10 | - **`http://idmanagement.gov/ns/assurance/aal/2?phishing_resistant=true`**
11 | This specifies that a user has been authenticated with a crytographically secure method, such as WebAuthn or using a PIV/CAC. Users must _always_ authenticate with a second factor.
12 | - **`http://idmanagement.gov/ns/assurance/aal/2?hspd12=true`**
13 | This specifies that a user has been authenticated with an HSPD12 credential (requires PIV/CAC). Users must _always_ authenticate with a second factor.
14 | {% endcapture %}
15 |
16 | {{ aal_values | markdownify }}
17 |
18 |
--------------------------------------------------------------------------------
/_includes/snippets/auth_content/deprecated_values.md:
--------------------------------------------------------------------------------
1 | {% capture deprecated_values %}
2 | These are not recommended, and only for legacy compatibility.
3 | - **`http://idmanagement.gov/ns/assurance/ial/1`**
4 | Requires basic identity assurance, does not require identity verification. Equivalent to `urn:acr.login.gov:auth-only`.
5 | - **`http://idmanagement.gov/ns/assurance/ial/2`**
6 | Requires that the user has gone through basic identity verification. Equivalent to `urn:acr.login.gov:verified`.
7 |
8 | Does not meet NIST 800-63-3 IAL2 standard.
9 | - **`http://idmanagement.gov/ns/assurance/loa/1`**
10 | Equivalent to `urn:acr.login.gov:auth-only`.
11 |
12 | - **`http://idmanagement.gov/ns/assurance/loa/3`**
13 | Equivalent to `urn:acr.login.gov:verified`.
14 | {% endcapture %}
15 |
16 | {{ deprecated_values | markdownify }}
17 |
--------------------------------------------------------------------------------
/_includes/snippets/auth_content/service_levels.md:
--------------------------------------------------------------------------------
1 | {% capture type_of_service %}
2 | A type of service level must be specified.
3 | - **`urn:acr.login.gov:auth-only`**
4 | Requires basic identity assurance: email address, password, and at least one MFA method. No identity verification.
5 |
6 | Meets either NIST 800-63-3 AAL1 or AAL2 standard (depending on agency integration configuration)
7 | - **`urn:acr.login.gov:verified`**
8 | Requires that the user has gone through basic identity verification without facial matching.
9 |
10 | Does not meet NIST 800-63-3 IAL2 standard.
11 | - **`urn:acr.login.gov:verified-facial-match-required`**
12 | Requires identity verification with facial match for **all** users. Even if a user has been previously verified without facial matching, they will be required to go through verification with facial match.
13 |
14 | Meets NIST 800-63-3 IAL2 standard.
15 | - **`urn:acr.login.gov:verified-facial-match-preferred`**
16 | Requires identity verification. Users with no previous identity verification will be required to go through a facial match. Users with previous identity verification will use that data, even if it was done without facial match.
17 |
18 | Authentications for users who verify with facial matching will meet NIST 800-63-3 IAL2 standard. Authentication for users who do not do facial matching will not meet NIST 800-63-3 IAL2 standard.
19 | {% endcapture %}
20 |
--------------------------------------------------------------------------------
/_includes/snippets/saml/logout/remote_logout.md:
--------------------------------------------------------------------------------
1 | {% capture remote_logout %}
2 | Login.gov also offers a remote / back channel logout endpoint if your application needs to log users out without redirecting them back to Login.gov. This is still **not** true Single Logout (SLO), it will only terminate a given user's session with Login.gov. You must still manage the session for your application separately.
3 |
4 | For remote logout, you must include a `SessionIndex` element in the SAML request that contains the user's Login.gov UUID. This will allow Login.gov to identify the user that needs to be logged out and terminate their session.
5 |
6 | To log a user out using a back channel request, send a **POST** request from your application to the remote logout URL with a `SAMLRequest` parameter:
7 |
8 | ```bash
9 | https://idp.int.identitysandbox.gov/api/saml/remotelogout{{ site.data.saml.year.current }}?SAMLRequest=${SAML_REQUEST}
10 | ```
11 |
12 | The `SAMLRequest` parameter is a url-encoded, base64-encoded, deflate-compressed XML payload of a ``.
13 |
14 | All remote logout requests must be signed — we require RSA SHA-256 signatures embedded with logout requests.
15 |
16 | An example remote logout request payload, with indentation added for readability.
17 |
18 | ```xml
19 |
25 | urn:gov:gsa:SAML:2.0.profiles:sp:sso:rails-int
26 | e1e99d8e-c590-4e0d-9530-e4d9611a4509
27 |
28 |
29 |
30 |
31 |
32 |
33 |
34 |
35 |
36 |
37 |
38 |
39 | 3uM6/dwG6J2StsI9uFMlvpaLIHs2OqacTW9h7cGXOcE=
40 |
41 |
42 | zxIZQaHhakrKzV1vISwql0Ua8HKudlPDw3g7mcO18yFt6oDtCR55e7RlcuBOQYRYM5wesbxyAZcglJaxVVheViK9REg87OU1RqCJElyUcXXK6ERdgXpOp0YCb/VorWU4y9UNrloqFzgRIJxKtqVPqLlC6KSpqZqOiABhGluleUaIOuhW9INEwmQyWVobGp6+/ZOBY1m1DnMCaEmB46qW2YhYTCrBy6Uv3ZIs/sZZhlkyU98hndyVfJmzCRPzLmhHuxQunhqFLnbPoB3lCzOn2fV5oNYHOTmkDfb90HZoyd9gj5YOynmd6AQsUebx6utWTtyQ9sYojPixjehos8Yd5w==
43 |
44 |
45 | MIIDejCCAmICCQDxlELhbJBQdzANBgkqhkiG9w0BAQUFADB/MRYwFAYDVQQDDA1TUCBSYWlscyBEZW1vMQwwCgYDVQQKDANHU0ExDDAKBgNVBAsMAzE4ZjETMBEGA1UEBwwKV2FzaGluZ3RvbjELMAkGA1UECAwCREMxCzAJBgNVBAYTAlVTMRowGAYJKoZIhvcNAQkBFgsxOGZAZ3NhLmdvdjAeFw0xNjA4MTgyMDIzMzNaFw0yNjA4MTYyMDIzMzNaMH8xFjAUBgNVBAMMDVNQIFJhaWxzIERlbW8xDDAKBgNVBAoMA0dTQTEMMAoGA1UECwwDMThmMRMwEQYDVQQHDApXYXNoaW5ndG9uMQswCQYDVQQIDAJEQzELMAkGA1UEBhMCVVMxGjAYBgkqhkiG9w0BCQEWCzE4ZkBnc2EuZ292MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6gWv5EDu88CgWTgo+B8+Rp7ZSjNKKdud2I4U6Bfr0IMerdrh1LVwO6JOli/qRRDqECQz7Jm6m4XnVvf1bUiQd8cn/FheQfD2NuDNfrnAvyIRIHDgGHGSx3vjPZJVYi5BVmEOPFEKYEKHqS/UGnNjkS2XsoAkstRe6gioo4Hd2WLwjuCMqgNA3vgwyVxdgfI5vsrm6q43X15wb/wCP4r2rGKGSUIIshZPeUcPOzBMAmwVqREN4ux79Ee5K/87aXBVRF7Z2tFV1d5KEXO3dCw+T6cspj9MjfY2976cQfBXWnDKGdNWaLdwtFqvpgo9IXRxlAmUQtx8SC8z+zXaSSGB/wIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQCtc97SZLs5eBx7LrxdaeP5hq2etB7l6uM6+l/eSvXu8LlQfTUT7URxX4hXbKyORs1BLpnMYxofeyJlzb9K0koy1ZFhUtBufvU1R+ouMfZlV3QGOUMIUp00UNS39b74214jpuUYi7oEM0gHBN3BXxVyzUEAzt2HYHp2Im97ERSmTMkvSfiqilx/t03qIuZVxzu+jIU2BQUxS7s6XQ2DpDbvfggmnvToCmNA0VSg9rZkziOLSRHblcUpdMYH8+mzbTCfgg/Of0kTDVqXzgNa/iR0HUq18bDf3iFebS/sugwXN3vCxdCnad64q5tqF+VscZEtc7Okech2OuctnWy0nzFQ
46 |
47 |
48 |
49 | 4985175e-3ddb-489a-a92c-c981cd15e3ca
50 |
51 | ```
52 |
53 | In response to a remote logout request Login.gov will render a [logout response](#logout-response).
54 | {% endcapture %}
55 |
An official website of the United States government
45 |
Here’s how you know
46 |
47 |
51 |
52 |
53 |
54 |
55 |
56 |
57 |
61 |
62 |
63 | Official websites use .gov
64 |
65 | A .gov website belongs to an official government organization in the United States.
66 |
67 |
68 |
69 |
70 |
74 |
75 |
76 | Secure .gov websites use HTTPS
77 |
78 | A lock (
79 |
83 | ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.
84 |
33 |
34 |
--------------------------------------------------------------------------------
/_pages/attributes.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: User attributes
3 | lead: >
4 | Login.gov user accounts are either identity proofed or self-asserted.
5 | ---
6 |
7 | Here are the possible attributes that can be requested at a given IAL. This table contains the available user attributes, the IAL they are associated with, and how they can be accessed in OpenID Connect (OIDC) and SAML.
8 |
9 | It is important to expect any number of characters in the `(string)` datatype unless directly followed by a number such as `(string36)`. Strings are encrypted and stored in a text datatype with a maximum length of 65,535 bytes.
10 |
11 |
12 | {% capture checkmark %}
13 |
14 |
17 |
18 | {% endcapture %}
19 |
20 |
21 |
22 |
Attribute
23 |
Auth Only
24 |
ID Proofed
25 |
OpenID Connect
26 |
SAML
27 |
28 |
29 |
30 |
31 | **UUID** The user's [universally unique identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier).
32 |
308 | `x509_issuer` (string)
309 |
310 | Requires the `x509:issuer` or `x509` scope.
311 |
312 |
313 | `x509_issuer` (string)
314 |
315 |
316 |
317 |
318 | **x509 Subject**
319 |
320 |
321 | {{ checkmark }}
322 |
323 |
324 | {{ checkmark }}
325 |
326 |
327 | `x509_subject` (string)
328 |
329 | Requires the `x509:subject` or `x509` scope.
330 |
331 |
332 | `x509_subject` (string)
333 |
334 |
335 |
336 |
337 | **x509 Presented**
338 |
339 |
340 | {{ checkmark }}
341 |
342 |
343 | {{ checkmark }}
344 |
345 |
346 | `x509_presented` (boolean)
347 |
348 | Requires the `x509:presented` or `x509` scope.
349 |
350 |
351 | `x509_presented` (string)
352 |
353 |
354 |
355 |
356 | * Please note that only `phone` and `verified_at` idV user attributes may be returned as null.
357 |
358 | [checkmark]: {{ site.baseurl }}/assets/img/check.svg
359 |
--------------------------------------------------------------------------------
/_pages/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Welcome to the Login.gov developer guide
3 | lead: >
4 | This developer guide contains everything you’ll need to integrate and deploy your application with Login.gov.
5 | permalink: /
6 | layout: home
7 | ---
8 |
9 |
20 | Your integration with Login.gov starts in the portal where you can register your app.
21 |
22 |
23 |
24 |
25 | Determine your application needs, like the level of proofing and user attributes that will be requested.
26 |
27 |
28 |
29 |
30 | Select between Open ID Connect (OIDC) or SAML implementation protocols.
31 |
32 |
33 |
34 |
35 | Configure your app in the portal and start testing! We have implementation guides and example apps to get you up and running quickly.
36 |
37 |
38 |
39 |
40 | When you are ready to go live our team will help you promote the application to production. We will check against our production checklist to ensure your application is ready for production from an administrative and technical standpoint.
41 |
42 |
43 |
44 |
45 |
46 |
Integration support for developers
47 |
48 | If you are with a government agency partner, check our [FAQ]({{ site.baseurl}}/support/#frequently-asked-questions) page for answers to the most common questions. If you need further technical assistance with an integration, you can [contact Partner Support]({{ site.baseurl}}/support/#contacting-partner-support).
49 |
50 |
51 | For help signing in or verifying your identity with Login.gov, please visit the Login.gov Help Center or contact us.
52 |
53 |
54 |
55 |
56 |
--------------------------------------------------------------------------------
/_pages/oidc/certificates.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: OpenID Connect
3 | lead: >
4 | [OpenID Connect](https://openid.net){:class="usa-link--external"} (OIDC) is a simple identity layer built on top of the OAuth 2.0 protocol. Login.gov supports [version 1.0](https://openid.net/specs/openid-connect-core-1_0.html){:class="usa-link--external"} of the specification and conforms to the [iGov Profile](https://openid.net/wg/igov){:class="usa-link--external"}.
5 | sidenav:
6 | - text: Getting started
7 | href: "oidc/getting-started/"
8 | - text: Authorization
9 | href: "oidc/authorization/"
10 | - text: Token
11 | href: "oidc/token/"
12 | - text: User info
13 | href: "oidc/user-info/"
14 | - text: Certificates
15 | href: "oidc/certificates/"
16 | - text: Logout
17 | href: "oidc/logout/"
18 |
19 | ---
20 |
21 | {% capture content %}
22 | ## Certificates
23 |
24 | Login.gov's public key, used to verify signed JWTs (such as the `id_token`), is available in [JWK](https://tools.ietf.org/html/rfc7517){:class="usa-link--external"} format at the `/api/openid_connect/certs` endpoint.
25 |
26 | This public key is rotated periodically (on at least an annual basis). It is important to assume the `/api/openid_connect/certs` endpoint could contain multiple JWKs when rotating application signing keys. Be sure to use the JWK endpoint dynamically through [auto-discovery](/oidc/getting-started/#auto-discovery) rather than hardcoding the public key. This ensures that your application will not require manual intervention when the Login.gov public key is rotated.
27 | {% endcapture %}
28 |
29 |
42 |
--------------------------------------------------------------------------------
/_pages/oidc/getting-started.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: OpenID Connect
3 | lead: >
4 | [OpenID Connect](https://openid.net){:class="usa-link--external"} (OIDC) is a simple identity layer built on top of the OAuth 2.0 protocol. Login.gov supports [version 1.0](https://openid.net/specs/openid-connect-core-1_0.html){:class="usa-link--external"} of the specification and conforms to the [iGov Profile](https://openid.net/wg/igov){:class="usa-link--external"}.
5 | redirect_from:
6 | - /openid-connect/
7 | - /oidc/
8 | sidenav:
9 | - text: Getting started
10 | href: "oidc/getting-started/"
11 | links:
12 | - text: Choosing an authentication method
13 | href: "#choosing-an-authentication-method"
14 | - text: Set up a Sandbox account
15 | href: "#set-up-a-sandbox-account"
16 | - text: Auto-discovery
17 | href: "#auto-discovery"
18 | - text: Example application
19 | href: "#example-application"
20 | - text: Authorization
21 | href: "oidc/authorization/"
22 | - text: Token
23 | href: "oidc/token/"
24 | - text: User info
25 | href: "oidc/user-info/"
26 | - text: Certificates
27 | href: "oidc/certificates/"
28 | - text: Logout
29 | href: "oidc/logout/"
30 |
31 | ---
32 | {% capture implicit_flow_warning %}
33 | We do not support the OpenID Connect (OIDC) “implicit flow” with client_secret because it is not recommended by the OAuth group for security reasons
34 | {% endcapture %}
35 | {% include alert.html content=implicit_flow_warning alert_class="usa-alert--warning" %}
36 |
37 |
38 | ## Getting started
39 |
40 | ### Choosing an authentication method
41 |
42 | Login.gov supports two ways of authenticating clients: **private_key_jwt** and **PKCE**.
43 |
44 | - **private_key_jwt** (preferred for web apps)
45 | The client sends a [JSON Web Token](https://jwt.io/){:class="usa-link--external"}, or JWT, signed with a private key (minimum length of 2048 bits) when requesting access tokens. The corresponding public key is registered with the IdP ahead of time, similar to SAML.
46 |
47 | - **PKCE** (preferred for native mobile apps)
48 | Short for [Proof Key for Code Exchange by OAuth Public Clients](https://tools.ietf.org/html/rfc7636){:class="usa-link--external"} and pronounced "pixy." In this method, the client sends a public identifier as well as a hashed random value generated by the client.
49 |
50 | ### Unsupported methods
51 |
52 | The following implementation methods of OIDC are not supported by Login.gov for security reasons.
53 |
54 | - **Implicit flow** is [not recommended by the OAuth group](https://oauth.net/2/grant-types/implicit/){:class="usa-link--external"}.
55 | - **client_secret_param** is not supported because it requires managing a shared secret in two places, both the client and the server. Private_key_jwt flow involves sharing public keys with the server and PKCE has a one-time secret.
56 |
57 | ### Set up a Sandbox account
58 |
59 | You are able to test authentication methods in real time with a testing account in our sandbox environment. To start, navigate to the [Login Partner Portal Sandbox](https://dashboard.int.identitysandbox.gov) and follow the steps below:
60 |
61 | - Select the “Sign-in” button to create a new account. Anyone with a .gov or .mil email address may request an account.
62 | - Create a new team - see [Testing](/testing/) page for instructions.
63 | - Create a certificate - before creating your application you'll need to create a certificate that will be used to sign your requests. You can create a certificate using openssl. The example command to create the certificate from your terminal is:
64 | - `openssl req -nodes -x509 -days 365 -newkey rsa:2048 -keyout private.pem -out public.crt`
65 | - Create an application, at which point you will need to decide between private_key_jwt or PKCE.
66 |
67 | It is important to note that your Login.gov production account and your Login.gov sandbox account are two separate accounts.
68 |
69 | ### Auto-discovery
70 |
71 | Consistent with the specification, Login.gov provides a JSON endpoint for OIDC auto-discovery at
72 | `/.well-known/openid-configuration`.
73 |
74 | Integration URI:
75 | - [https://idp.int.identitysandbox.gov/.well-known/openid-configuration](https://idp.int.identitysandbox.gov/.well-known/openid-configuration)
76 |
77 | Production URI:
78 | - [https://secure.login.gov/.well-known/openid-configuration](https://secure.login.gov/.well-known/openid-configuration)
79 |
80 | ### Example Application
81 |
82 | The Login.gov team has created an example client to speed up your development, all open source in the public domain: [identity-oidc-sinatra](https://github.com/18F/identity-oidc-sinatra){:class="usa-link--external"}.
83 |
84 | [Next step: Authorization]({{ site.baseurl }}/oidc/authorization/){:class="margin-top-4"}
85 |
--------------------------------------------------------------------------------
/_pages/oidc/logout.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: OpenID Connect
3 | lead: >
4 | [OpenID Connect](https://openid.net){:class="usa-link--external"} (OIDC) is a simple identity layer built on top of the OAuth 2.0 protocol. Login.gov supports [version 1.0](https://openid.net/specs/openid-connect-core-1_0.html){:class="usa-link--external"} of the specification and conforms to the [iGov Profile](https://openid.net/wg/igov){:class="usa-link--external"}.
5 | sidenav:
6 | - text: Getting started
7 | href: "oidc/getting-started/"
8 | - text: Authorization
9 | href: "oidc/authorization/"
10 | - text: Token
11 | href: "oidc/token/"
12 | - text: User info
13 | href: "oidc/user-info/"
14 | - text: Certificates
15 | href: "oidc/certificates/"
16 | - text: Logout
17 | href: "oidc/logout/"
18 | links:
19 | - text: Logout request
20 | href: "#logout-request"
21 | - text: Logout response
22 | href: "#logout-response"
23 |
24 | ---
25 |
26 |
27 |
28 |
29 | ## Logout
30 |
31 | Login.gov supports [RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html){:class="usa-link--external"}, allowing clients to log users out of their current Login.gov session and redirect them back to the Relying Party.
32 |
33 | Login.gov does not support Single Logout (SLO). The logout action will terminate the user’s session at Login.gov but will not end any other potentially active sessions within service provider applications. For example, if a user signs in to applications A and B through Login.gov, a logout request from A will end their Login.gov session, but will not affect the session in application B.
34 |
35 | **User experience impact:**
36 |
37 | As per the OIDC spec, Login.gov will display a Logout confirmation screen to users on logout. Users will need to click a button to complete the logout process. This protects against forged logout request attacks.
38 |
39 | If the user does not click the button, they will **not** be redirected back to your application.
40 |
41 | ### Logout request
42 |
43 | To log out a user, send them to the `/openid_connect/logout` endpoint with the following parameters:
44 |
45 |
46 |
47 |
48 |
client_id
49 |
50 |
51 |
52 | The unique identifier for the client. This will be registered with the Login.gov IdP in advance.
53 |
54 |
55 |
56 |
57 |
58 |
59 |
60 |
post_logout_redirect_uri
61 |
62 |
63 |
64 | The URI Login.gov will redirect to after logout. This must also be registered with the Login.gov IdP in advance.
65 |
66 |
67 |
68 |
69 |
70 |
71 |
72 |
state (optional)
73 |
74 |
75 |
76 | A unique value at least 22 characters in length used for maintaining state between the request and the callback. This value will be returned to the client on a successful logout as a parameter of state added to the redirect back to the post_logout_redirect_uri.
77 |
78 |
79 |
80 |
81 |
82 | ### Logout response
83 |
84 | In a **successful logout**, i.e. the request is valid and the user confirms that they want to log out, Login.gov will redirect the user to the provided `post_logout_redirect_uri` with the `state` parameter added to the URL. If the request is invalid, the user will be shown an error page.
85 |
86 | If the user declines to click the button on the confirmation page, they will not be redirected to the `post_logout_redirect_uri` and there will be no response to your application.
87 |
88 |
89 |
104 |
--------------------------------------------------------------------------------
/_pages/oidc/user-info.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: OpenID Connect
3 | lead: >
4 | [OpenID Connect](https://openid.net){:class="usa-link--external"} (OIDC) is a simple identity layer built on top of the OAuth 2.0 protocol. Login.gov supports [version 1.0](https://openid.net/specs/openid-connect-core-1_0.html){:class="usa-link--external"} of the specification and conforms to the [iGov Profile](https://openid.net/wg/igov){:class="usa-link--external"}.
5 | sidenav:
6 | - text: Getting started
7 | href: "oidc/getting-started/"
8 | - text: Authorization
9 | href: "oidc/authorization/"
10 | - text: Token
11 | href: "oidc/token/"
12 | - text: User info
13 | href: "oidc/user-info/"
14 | links:
15 | - text: User info response
16 | href: "#user-info-response"
17 | - text: Certificates
18 | href: "oidc/certificates/"
19 | - text: Logout
20 | href: "oidc/logout/"
21 |
22 | ---
23 | {% capture front_matter %}
24 | ## User info
25 |
26 | The user info endpoint is used to retrieve [user attributes]({{ site.baseurl }}/attributes/). Clients use the `access_token` from the [token response]({{ site.baseurl }}/oidc/token/#token-response) as a bearer token in the [HTTP Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization){:class="usa-link--external"}. To request attributes, send an HTTP GET request to the `/api/openid_connect/userinfo` endpoint. View an example request and response in the side panel.
27 |
28 | ### User info response
29 |
30 | The user info response will be a JSON object containing [user attributes]({{ site.baseurl }}/attributes/). Login.gov supports some of the [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims){:class="usa-link--external"} from OIDC 1.0. In addition to the user attributes, the following information will also be present:
31 | {% endcapture %}
32 |
33 |
34 |
35 | {{ front_matter | markdownify }}
36 |
37 |
38 |
iss (string)
39 |
40 |
41 |
42 | The issuer of the response, which will be the URL of the Login.gov IdP, for example: https://idp.int.identitysandbox.gov
43 |
44 |
45 |
46 |
47 |
48 |
email_verified (boolean)
49 |
50 |
51 |
52 | Whether the email has been verified. Currently, Login.gov only supports verified emails.
53 |
54 |
55 |
Requires email scope
56 |
57 |
58 |
59 |
60 |
61 |
phone_verified (boolean)
62 |
63 |
64 |
65 | Whether the phone number has been verified. Currently, Login.gov only supports verified phones.
66 |
67 |
68 |
Requires the phone scope and an identity verified account
69 |
70 |
71 |
72 |
73 |
74 |
verified_at (number, null)
75 |
76 |
77 |
78 | When the user's identity was last verified, as an integer timestamp representing the number of seconds since the Unix Epoch, or null if the account has never been verified.
79 |
101 |
102 |
--------------------------------------------------------------------------------
/_pages/overview.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Integration overview and user flow
3 | sidenav:
4 | - text: User flow
5 | href: "#user-flow"
6 | - text: Service provider configuration
7 | href: "#service-provider-configuration"
8 | ---
9 |
10 | 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.
11 |
12 | ## User flow
13 |
14 |
15 |
18 | Fig. 1: Authentication flow
19 |
20 |
21 | * Once you have successfully integrated your application with the Login.gov environment, users start at your application and are redirected back to Login.gov via [OpenID Connect (OIDC)]({{ site.baseurl }}/oidc/) or [SAML]({{ site.baseurl }}/saml/) protocols.
22 | * The service level you specify via the authentication request sent by your application will determine the type of verification required for the user’s account. Identity proofed accounts require the user to complete additional steps to verify their identity in addition to the Multifactor Authentication (MFA).
23 | * New users will create an account corresponding to the identity assurance level requested. Returning users will present their existing Login.gov credentials to authenticate with Login.gov. A new user to your application will consent to their information being shared with your application upon creating an account.
24 | * Upon successful completion of the account creation and authentication, users will be redirected back to your application with the [user attributes]({{ '/attributes/' | prepend: site.baseurl }}) that correspond to their user level.
25 | * With the attributes provided by Login.gov, your application will handle authorization of the user and assign roles and permissions.
26 |
27 | ## Service provider configuration
28 |
29 | This is the configuration for your application within Login.gov’s identity provider. In the sandbox environment, you will be able to determine the configuration yourself and decide what is the best fit for your needs. In the Login.gov production environment, we will manage the final configuration.
30 | To configure a test application in the sandbox environment:
31 | * Create an account in the [Login.gov Portal](https://portal.int.identitysandbox.gov). From here you will be able to test various configurations and determine what is right for your agency.
32 | * Select between [OIDC]({{ site.baseurl }}/oidc/) or [SAML]({{ site.baseurl }}/saml/) protocol implementation protocols and understand which user attributes are required.
33 | * If you have questions when testing your app, read through our [FAQs]({{ site.baseurl }}/support/) or submit a ticket to our [technical support help desk]({{ site.baseurl}}/support/#contacting-partner-support).
34 | * Before submitting a request to move your app to production, review the [User experience]({{ site.baseurl }}/design-guidelines/) page and the [Production]({{ site.baseurl }}/production/) page. Additional requirements, like a [signed Interagency agreement]({{ site.baseurl }}/production/#confirm-interagency-agreement-iaa) (IAA) and [agency logo]({{ site.baseurl }}/user-experience/agency-logo/), are described in these pages.
35 |
--------------------------------------------------------------------------------
/_pages/push-notifications.md:
--------------------------------------------------------------------------------
1 | ---
2 | redirect_to: /security-events/
3 | ---
--------------------------------------------------------------------------------
/_pages/risc.json:
--------------------------------------------------------------------------------
1 | ---
2 | permalink: /data/risc.json
3 | layout: none
4 | ---
5 | {%- capture json -%}
6 | {
7 | "supported_events": [
8 | {% for event in site.data.risc_incoming %}
9 | {% include risc_event.json event=event direction="incoming" %}
10 | ,
11 | {% endfor %}
12 | {% for event in site.data.risc_outgoing %}
13 | {% include risc_event.json event=event direction="outgoing" %}
14 | {% unless forloop.last %},{% endunless %}
15 | {% endfor %}
16 | ]
17 | }
18 | {%- endcapture -%}
19 | {{ json | pretty_jsonify }}
--------------------------------------------------------------------------------
/_pages/saml/authentication.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: SAML developer guide
3 | lead: >
4 | Login.gov is a standard SAML identity provider, adhering to the [Web Browser SSO Profile](https://en.wikipedia.org/wiki/SAML_2.0#Web_browser_SSO_profile){:class="usa-link--external"} with enhancements for [NIST 800-63-3](https://pages.nist.gov/800-63-3/){:class="usa-link--external"}.
5 | redirect_from:
6 | - /configuring-your-sp/
7 | - /saml/
8 | sidenav:
9 | - text: Getting started
10 | href: "/saml/getting-started/"
11 | - text: Authentication
12 | href: "/saml/authentication/"
13 | links:
14 | - text: Authentication request
15 | href: "/saml/authentication/#authentication-request"
16 | - text: Authentication response
17 | href: "/saml/authentication/#authentication-response"
18 | - text: Logout
19 | href: "/saml/logout/"
20 | ---
21 | {% capture aal_values %}
22 | {% include snippets/auth_content/aal_values.md %}
23 | {% endcapture %}
24 | {% capture service_levels %}
25 | {% include snippets/auth_content/service_levels.md %}
26 | {% endcapture %}
27 | {% capture deprecated_values %}
28 | {% include snippets/auth_content/deprecated_values.md %}
29 | {% endcapture %}
30 | {% capture saml_request_intro %}
31 | `SAML_REQUEST = urlEncode(base64(deflate(payload)))`
32 | {% endcapture %}
33 | {% capture saml_tag %}
34 | The `` tags (nested under `//samlp:AuthnRequest/samlp:RequestedAuthnContext/`) specify the type of identity verification, AAL (Authentication Assurance Level) and attributes requested.
35 | {% endcapture %}
36 | {% capture attributes %}
37 | To request specific attributes, list them (comma-separated) as the query parameter for `http://idmanagement.gov/ns/requested_attributes?ReqAttr=`. See the [user attributes]({{ '/attributes/' | prepend: site.baseurl }}) for the list of attributes that can be requested.
38 |
39 | #### Example specifying IAL, AAL, and attributes
40 |
41 | A proofed identity request at AAL2, with phishing resistent MFA, for email, phone, first name, last name, and SSN might look like:
42 |
43 | ```xml
44 |
45 |
46 |
47 | urn:acr.login.gov:verified
48 | http://idmanagement.gov/ns/assurance/aal/2?phishing_resistant=true
49 | http://idmanagement.gov/ns/requested_attributes?ReqAttr=email,phone,first_name,last_name,ssn
50 |
51 |
52 | ```
53 | {% endcapture %}
54 |
55 |
56 |
57 |
Authentication
58 |
Authentication request
59 |
To authenticate a user with Login.gov, direct them to our authentication URL with a SAML authentication request as a GET param.
60 |
The SAMLRequest parameter is a url-encoded, base64-encoded, deflate-compressed XML payload. IE: {{ saml_request_intro | markdownify }}
61 |
Note: We strongly encourage you to cryptographically sign authentication requests. In addition to providing increased security, this allows for seamless rotation of your application’s public certificate in the future. All signatures must use RSA SHA-256.
62 |
63 |
64 |
65 |
Specifying attributes and assurance levels
66 |
67 |
68 | {{ saml_tag | markdownify }}
69 |
70 |
71 |
72 | {% include accordion.html content=service_levels accordion_id="service_level_accordion" title="Type of Service Level" id="service_level" %}
73 | {% include accordion.html content=aal_values accordion_id="aal_accordion" title="Authentication Assurance (AAL) Values" id="aal_values" %}
74 | {% include accordion.html content=attributes accordion_id="attributes_accordion" title="Attributes" id="attributes" %}
75 | {% include accordion.html content=deprecated_values accordion_id="deprecated_accordion" title="Deprecated Service Values" id="deprecated_values" %}
76 |
77 |
78 |
79 |
80 |
81 |
RelayState
82 |
83 |
84 |
If you need to pass any information about the request back to your application after the authentication process is complete (e.g. the path to direct the user to), you can include a RelayState query parameter with up to 80 bytes of information. This will be included in the response back to your application as per section 3.4.3 of the SAML 2.0 bindings spec.
If you know that a user would prefer one of our alternative language translations (currently Spanish or French), you can include the locale parameter to specify the language Login.gov should use (either ES for Spanish or FR for French), e.g.:
135 |
136 |
137 |
--------------------------------------------------------------------------------
/_pages/saml/getting-started.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: SAML developer guide
3 | lead: >
4 | Login.gov is a standard SAML identity provider, adhering to the [Web Browser SSO Profile](https://en.wikipedia.org/wiki/SAML_2.0#Web_browser_SSO_profile){:class="usa-link--external"} with enhancements for [NIST 800-63-3](https://pages.nist.gov/800-63-3/){:class="usa-link--external"}.
5 | redirect_from:
6 | - /configuring-your-sp/
7 | - /saml/
8 | sidenav:
9 | - text: Getting started
10 | href: "/saml/getting-started/"
11 | links:
12 | - text: Configuration
13 | href: "/saml/getting-started/#configuration"
14 | - text: Metadata
15 | href: "/saml/getting-started/#metadata"
16 | - text: Signing Certificates
17 | href: "/saml/getting-started/#signing-certificates"
18 | - text: Annual Certificate Rotation
19 | href: "/saml/getting-started/#annual-certificate-rotation"
20 | - text: Example application
21 | href: "/saml/getting-started/#example-application"
22 | - text: Authentication
23 | href: "/saml/authentication/"
24 | - text: Logout
25 | href: "/saml/logout/"
26 | ---
27 | {% capture nameid %}
28 | 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](https://tools.ietf.org/html/rfc4122){:class="usa-link--external"}.
29 |
30 | For example:
31 | `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
32 | {% endcapture %}
33 |
34 | {% capture login %}
35 | This is the endpoint where authentication requests are sent to Login.gov (aka Single Sign-on Service).
36 |
37 | For example:
38 | ``
39 | {% endcapture %}
40 |
41 | {% capture logout %}
42 | The single logout service URL is used to contact the Single logout profile (aka Single Logout Service).
43 |
44 | For example:
45 | ``
46 | {% endcapture %}
47 |
48 | {% capture saml_warning %}
49 | We strongly recommend choosing [OpenID Connect]({{site.baseurl}}/oidc/getting-started/) (OIDC) over SAML due to its modern, API-centric design and support for native mobile applications.
50 | {% endcapture %}
51 | {% include alert.html content=saml_warning alert_class="usa-alert--warning" %}
52 |
53 |
54 |
55 |
56 | ## Getting started
57 |
58 | 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.
59 |
60 | ### Configuration
61 |
62 | Here are values needed to configure your service provider (SP) to work with Login.gov:
63 |
64 |
65 |
66 |
67 |
NameID Format
68 |
69 |
70 | {{ nameid | markdownify }}
71 |
72 |
73 |
74 |
75 |
76 |
77 |
Login service URL and Binding
78 |
79 |
80 | {{ login | markdownify }}
81 |
82 |
83 |
84 |
85 |
86 |
87 |
Logout service URL and Binding
88 |
89 |
90 | {{ logout | markdownify}}
91 |
92 |
93 |
94 |
95 | ### x509 Public Certificate
96 | 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](#metadata) and below for verification.
97 |
98 | ### Metadata
99 |
100 | Consistent with the [SAML metadata specification](https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf){:class="usa-link--external"}, Login.gov's metadata for our sandbox environment is available at [https://idp.int.identitysandbox.gov/api/saml/metadata{{ site.data.saml.year.current }}](https://idp.int.identitysandbox.gov/api/saml/metadata{{ site.data.saml.year.current }}).
101 |
102 | ### Signing Certificates
103 | Below you can find the X509 certificates used by the Login.gov IdP to sign SAML requests. **Do not enter these certificates in the Portal when configuring an application for testing** - you can follow the instructions in our [testing article]({% link _pages/testing.md %}#creating-a-public-certificate) to generate a client certificate.
104 |
105 |
126 |
127 | #### Annual Certificate Rotation
128 |
129 | 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.
130 |
131 | - `/api/saml/auth{{ site.data.saml.year.previous }}` becomes `/api/saml/auth{{ site.data.saml.year.current }}`
132 | - `/api/saml/logout{{ site.data.saml.year.previous }}` becomes `/api/saml/logout{{ site.data.saml.year.current }}`
133 |
134 | 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.
135 |
136 | The {{ site.data.saml.year.previous }} certificates for idp.int.identitysandbox.gov and secure.login.gov each expire on April 1, {{ site.data.saml.year.current }}. So the transition from {{ site.data.saml.year.previous }} to {{ site.data.saml.year.current }} endpoints should take place in February or March {{ site.data.saml.year.current }}.
137 |
138 | #### Example application
139 |
140 | The Login.gov team has created an example client to speed up your development, all open source in the public domain: [identity-saml-sinatra](https://github.com/18F/identity-saml-sinatra){:class="usa-link--external"}.
141 |
142 | [Next step: Authentication]({{ '/saml/authentication/' | prepend: site.baseurl }})
143 |
144 |
22 |
23 | ## Logout
24 |
25 | ### Logout request
26 |
27 | Login.gov does not support Single Logout (SLO). The logout action will terminate the user's session at Login.gov but will not end any other potentially active sessions within service provider applications. For example, if a user signs in to applications A and B through Login.gov, a logout request from A will end their Login.gov session, but will not affect the session in application B.
28 |
29 | To log a user out, direct them to the logout URL with a `SAMLRequest`:
30 |
31 | The `SAMLRequest` parameter is a base64-encoded, deflate-compressed XML payload of a ``.
32 |
33 | All logout requests must be signed — we require RSA SHA-256 signatures embedded with logout requests.
34 |
50 |
51 | ### Logout response
52 |
53 | After, Login.gov will redirect and POST a form back to your registered Assertion Consumer Service Logout URL:
54 |
55 | Note: the SAMLResponse does not contain a signature since it's simply acknowledging the logout request.
56 |
57 |
58 |
59 |
62 |
63 | {% include snippets/saml/logout/remote_logout.md %}
64 |
77 | {% include icon_list.html icon_name="check_circle" content="Upload a logo that is high contrast on a transparent background" style="text-success" %}
78 |
79 |
80 | {% include icon_list.html icon_name="check_circle" content="Both .svg and .png files up to 50 kB are accepted" style="text-success" %}
81 |
82 |
83 |
84 | [Next step: Determine your application’s Cancel URL]({{ site.baseurl }}/user-experience/cancel-url/)
85 |
--------------------------------------------------------------------------------
/_pages/user-experience/cancel-url.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: User Experience
3 | lead: >
4 | Create a simple and consistent experience for your Login.gov users
5 | sidenav:
6 | - text: Getting started
7 | href: "user-experience/getting-started/"
8 | - text: Sign-in and sign-out buttons
9 | href: "user-experience/sign-in-sign-out/"
10 | - text: Help text guidance
11 | href: "user-experience/help-text/"
12 | - text: Your agency logo
13 | href: "user-experience/agency-logo/"
14 | - text: Cancel URL
15 | href: "user-experience/cancel-url/"
16 | links:
17 | - text: OIDC Redirect URI
18 | href: "#oidc-redirect-uri"
19 | - text: SAML Return to SP URL
20 | href: "#saml-return-to-sp-url"
21 | - text: Failure to proof URL
22 | href: "user-experience/failure-proof/"
23 | - text: Knowledge articles
24 | href: "user-experience/knowledge-articles/"
25 | - text: FAQ content
26 | href: "user-experience/faq-content/"
27 |
28 | ---
29 |
30 | ## Determine your application’s return to service provider URL
31 |
32 | When a user does not authenticate successfully, they should be returned to the service provider application to restart the authentication process. It is important that the user returns to a familiar site and that they have a clear path back to the authentication workflow.
33 |
34 | Depending on the type of integration (OIDC or SAML) you will need to set the `redirect_uri` or the `return_to_sp_url`.
35 |
36 | ### OIDC Redirect URI:
37 |
38 | Your integration should include a redirect URI for successful authentication attempts and canceled authentication attempts. Ideally, the user will be returned to the app site or the Login.gov form and can restart the authentication process. The URIs can be public, internal, or localhost, or a custom scheme to support native applications, for example: `gov.agency.app://result`.
39 |
40 | ### SAML Return to SP URL:
41 |
42 | This URL will be used if a user chooses to cancel out of the authentication workflow or return to the app site. For example, users would be returned to: `https://app.agency.gov`.
43 |
44 | [Next step: For Identity Verification permitted applications, determine your application’s failure to proof URL]({{ site.baseurl }}/user-experience/failure-proof/)
45 |
--------------------------------------------------------------------------------
/_pages/user-experience/failure-proof.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: User Experience
3 | lead: >
4 | Create a simple and consistent experience for your Login.gov users
5 | sidenav:
6 | - text: Getting started
7 | href: "user-experience/getting-started/"
8 | - text: Sign-in and sign-out buttons
9 | href: "user-experience/sign-in-sign-out/"
10 | - text: Help text guidance
11 | href: "user-experience/help-text/"
12 | - text: Your agency logo
13 | href: "user-experience/agency-logo/"
14 | - text: Cancel URL
15 | href: "user-experience/cancel-url/"
16 | - text: Failure to proof URL
17 | href: "user-experience/failure-proof/"
18 | links:
19 | - text: What is a Failure to Proof URL?
20 | href: "user-experience/failure-proof/#what-is-a-failure-to-proof-url"
21 | - text: Where should the Failure to Proof URL take users?
22 | href: "user-experience/failure-proof/#where-should-the-failure-to-proof-url-take-users"
23 | - text: Knowledge articles
24 | href: "user-experience/knowledge-articles/"
25 | - text: FAQ content
26 | href: "user-experience/faq-content/"
27 |
28 | ---
29 |
30 | ## Identity Verification: Create a Failure to Proof URL
31 | Applications with Login.gov identity verification need to provide an alternative proofing path to support users who are unable to complete Login.gov’s process.
32 |
33 | ### What is a Failure to Proof URL?
34 | Login.gov’s agency partners provide a link that their users are directed to if they are unable to verify their identity with Login.gov. This is called the Failure to Proof URL (e.g. `failure_to_proof_url`). This link routes users to a designated page on the agency partner’s site which is configured as part of the agency's integration.
35 |
36 | The Failure to Proof URL is shown to users throughout the identity proofing process. Some examples of when a user might encounter this are:
37 |
38 | - Users might navigate to this page if they don’t have a valid state-issued ID or Social Security number.
39 | - The Failure to Proof URL is available for users who are not able to capture or upload photos of their ID.
40 | - Users see the Failure to Proof URL when they encounter errors verifying their ID, personal information, or phone number. Examples of this include:
41 | - Users who enter valid information, but are not able to pass Login.gov’s proofing process because we cannot verify their information.
42 | - Users who have run out of attempts to verify their information.
43 |
44 | ### Where should the Failure to Proof URL take users?
45 |
46 | The purpose of the Failure to Proof URL is to provide an actionable next step for users who do not have the required information to complete remote identity verification or otherwise cannot pass the process through Login.gov. The agency’s designated destination page should include instructions for users on what to do to access the agency partner’s services.
47 |
48 | Want to discuss options for your Failure to Proof URL?
53 | Contact us
54 |
55 |
56 | [Next step: Create knowledge articles for Login.gov customer support]({{ site.baseurl }}/user-experience/knowledge-articles/)
57 |
--------------------------------------------------------------------------------
/_pages/user-experience/faq-content.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: User Experience
3 | lead: >
4 | Create a simple and consistent experience for your Login.gov users
5 | sidenav:
6 | - text: Getting started
7 | href: "user-experience/getting-started/"
8 | - text: Sign-in and sign-out buttons
9 | href: "user-experience/sign-in-sign-out/"
10 | - text: Help text guidance
11 | href: "user-experience/help-text/"
12 | - text: Your agency logo
13 | href: "user-experience/agency-logo/"
14 | - text: Cancel URL
15 | href: "user-experience/cancel-url/"
16 | - text: Failure to proof URL
17 | href: "user-experience/failure-proof/"
18 | - text: Knowledge articles
19 | href: "user-experience/knowledge-articles/"
20 | - text: FAQ content
21 | href: "user-experience/faq-content/"
22 |
23 | ---
24 |
25 | ## Add FAQ content to inform users about Login.gov (Optional)
26 |
27 | When you first integrate with Login.gov, we recommend adding frequently asked questions (FAQ) content to ensure that users are able to understand that your application uses Login.gov as a sign-in service. The next few sections outline plain language for agencies to leverage when creating that content.
28 |
29 | ### What is Login.gov?
30 | Login.gov is a sign in service that offers secure and private online access to government programs, such as federal benefits, services and applications. With a Login.gov account, you can sign in to multiple government websites with the same email address and password. [Learn more about Login.gov](https://login.gov/).
31 |
32 | ### Why is [YOUR APPLICATION] using Login.gov?
33 | [APPLICATION] chose Login.gov as their sign-in provider as a security measure. This service requires you to use an email address, password and two-factor authentication, sometimes referred to as multi-factor authentication, to sign-in. The use of two-factor authentication is an added layer of security to protect your private and sensitive information from hackers and password compromises.
34 |
35 | **[Identity Verification ONLY]** In addition to meeting the above requirements for multi-factor authentication, Login.gov asks users to upload a photograph of their state-issued ID and share their address, phone number and other personal information which is then verified against authoritative sources. Verifying your identity makes sure the right person has access to the right information. We are using Login.gov’s simple and secure process to keep your sensitive information safe.
36 |
37 | ### How do I create a Login.gov account?
38 | Start by selecting sign-in on [APPLICATION home page or link]. You’ll automatically be taken to the Login.gov sign-in page. You can create an account or sign in if you already have a Login.gov account. Login.gov is only the sign-in service. Once you sign in, you’ll be directed to your [APPLICATION] account or profile.
39 |
40 | Login.gov requires you to use a multifactor authentication method. You can select to receive a code via SMS/Text or phone call or use an authentication application, government PIV/CAC card, face or touch unlock, security key or download backup codes. We encourage you to add more than one authentication method to your account to avoid getting locked out if you ever lose an authentication method. Learn more about the different authentication methods you can use.
46 |
47 | ### How do I sign in to [APPLICATION] after I create my Login.gov account?
48 | Every time you click on Sign In on the APPLICATION site, you’ll go to the Login.gov sign in page. Enter your Login.gov email address, password and use your two-factor authentication method. Once you enter this information correctly, you’ll be signed in and automatically directed back to the APPLICATION site.
49 |
50 | ### Can I use my existing [APPLICATION] username and password to sign in?
51 | No. Your old username and password will no longer work. You must create a new account or use your existing Login.gov account to sign in. We’ll connect your new Login.gov account with your existing [APPLICATION] profile during the process.
52 |
53 | ### What if I already have a Login.gov account?
54 | If you already have a Login.gov account, you don’t need to create a second one. Use your existing Login.gov email address, password and a two-factor authentication method to sign in to [APPLICATION].
55 |
56 | ### What email address do I use to create a Login.gov account?
57 | If you don’t have an [APPLICATION] profile, we recommend you use a personal email address that you control. We recommend you don’t use a work email address. Why? If you leave your job, you’ll no longer have access to that email address. Without access to that email address, it will be much harder to verify who you are, if you ever need to reset your password. You also can’t use an email address you share with someone else.
58 |
59 | ### Can I share a Login.gov account with another person?
60 | No. Each person must set up their own Login.gov account, with their own personal email address (not an email that you share with someone else).
61 |
62 | ### Where do I get support for my Login.gov account?
63 | Login.gov can only help you resolve issues around signing in. For example, you would contact Login.gov if you have questions about your password or two-factor authentication method.
64 |
65 | Please keep in mind Login.gov cannot reset, delete or access your account on your behalf if you are locked out. You’ll need to delete your account and start again.
66 |
67 | We encourage you to add more than one two-factor authentication method and to keep your username and password in a safe place. Visit the Login.gov Help center to learn more.
73 |
74 | ### Can Login.gov help me with my [APPLICATION] benefits, services, application or profile?
75 | No. You still need to contact [AGENCY] for questions about your [APPLICATION] benefits, services, application or profile. [IF APPLICABLE] Our customer support can be reached [info].
76 |
77 |
--------------------------------------------------------------------------------
/_pages/user-experience/getting-started.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: User Experience
3 | lead: >
4 | Create a simple and consistent experience for your Login.gov users
5 | redirect_from:
6 | - /user-experience/
7 | - /design-guidelines/
8 | sidenav:
9 | - text: Getting started
10 | href: "user-experience/getting-started/"
11 | - text: Sign-in and sign-out buttons
12 | href: "user-experience/sign-in-sign-out/"
13 | - text: Help text guidance
14 | href: "user-experience/help-text/"
15 | - text: Your agency logo
16 | href: "user-experience/agency-logo/"
17 | - text: Cancel URL
18 | href: "user-experience/cancel-url/"
19 | - text: Failure to proof URL
20 | href: "user-experience/failure-proof/"
21 | - text: Knowledge articles
22 | href: "user-experience/knowledge-articles/"
23 | - text: FAQ content
24 | href: "user-experience/faq-content/"
25 |
26 | ---
27 |
28 | ## Getting started
29 | There are several decisions during the integration process that affect how your users experience Login.gov. In this User Experience guide, we will outline what options you have available to your application, and the configurations in Login.gov [portal](https://dashboard.int.identitysandbox.gov/) that impact users.
30 |
31 | {% capture button_ux %}
32 | [Design your application's sign-in and sign-out buttons]({{site.baseurl}}/user-experience/sign-in-sign-out/). This will include a [global sign-in button]({{site.baseurl}}/user-experience/sign-in-sign-out/), and optionally, [a sign-in page]({{site.baseurl}}/user-experience/sign-in-sign-out/) before the user is directed to Login.gov.
33 | {% endcapture %}
34 |
35 | {% capture failure_to_proof_ux %}
36 | All partners with identity verification will [create a Failure to Proof URL]({{site.baseurl}}/user-experience/failure-proof/) for users who cannot pass identity proofing with Login.gov. This URL is configured in the sandbox portal, but may require designing a new page or process on your agency's website or application.
37 | {% endcapture %}
38 |
39 | {% capture link_to_helpdesk %}
40 | Include a link to the [self-service Login.gov help center](https://login.gov/help/). (Do not publish the help center phone number on your application.)
41 | {% endcapture %}
42 |
43 | {% capture faq_ux %}
44 | Optional: [Add FAQ content to inform users about Login.gov]({{site.baseurl}}/user-experience/faq-content/)
45 | {% endcapture %}
46 |
47 | {% capture logo_ux %}
48 | [Add your agency logo]({{site.baseurl}}/user-experience/agency-logo/) to help users understand the partnership between Login.gov and your agency.
49 | {% endcapture %}
50 |
51 | {% capture cancel_url_ux %}
52 | [Determine your application’s Cancel URL]({{site.baseurl}}/user-experience/cancel-url/)
53 | {% endcapture %}
54 |
55 | {% capture dashboard_failure_to_proof %}
56 | [Identity Verification: Create a Failure to Proof URL]({{site.baseurl}}/user-experience/failure-proof/)
57 | {% endcapture %}
58 |
59 |
60 | ### Add to your agency's application
61 |
62 |
90 |
91 | [Next step: Design your application's sign-in and sign-out buttons]({{site.baseurl}}/user-experience/sign-in-sign-out/)
92 |
93 |
--------------------------------------------------------------------------------
/_pages/user-experience/help-text.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: User Experience
3 | lead: >
4 | Create a simple and consistent experience for your Login.gov users
5 | sidenav:
6 | - text: Getting started
7 | href: "user-experience/getting-started/"
8 | - text: Sign-in and sign-out buttons
9 | href: "user-experience/sign-in-sign-out/"
10 | - text: Help text guidance
11 | href: "user-experience/help-text/"
12 | - text: Your agency logo
13 | href: "user-experience/agency-logo/"
14 | - text: Cancel URL
15 | href: "user-experience/cancel-url/"
16 | - text: Failure to proof URL
17 | href: "user-experience/failure-proof/"
18 | - text: Knowledge articles
19 | href: "user-experience/knowledge-articles/"
20 | - text: FAQ content
21 | href: "user-experience/faq-content/"
22 |
23 | ---
24 |
25 | ## Help text guidance
26 |
27 | You may include help text to alert the users to specific information that will assist them in logging in, signing up, and logging out. The help text section of the app configuration workflow allows you to choose from the default help text options or request custom help text specific to your integration.
28 |
29 | Custom help text should follow the guidelines below to be included in your integration:
30 |
31 |
32 |
33 |
34 | {% include icon_list.html icon_name="check_circle" content="Help text should be brief, specific, and useful. It should add to the information already displayed on the page." style="text-success" %}
35 |
36 |
37 | {% include icon_list.html icon_name="check_circle" content="Include agency-specific contact information if needed." style="text-success" %}
38 |
39 |
40 | {% include icon_list.html icon_name="check_circle" content="Include Spanish and French translations of your custom help text." style="text-success" %}
41 |
42 |
43 | {% include icon_list.html icon_name="cancel" style="text-error" content="Repeat general instructions to complete the process (eg Sign in here)." %}
44 |
45 |
46 | {% include icon_list.html icon_name="cancel" style="text-error" content="Include legal disclaimers. These should be displayed on a separate page." %}
47 |
48 |
49 | {% include icon_list.html icon_name="cancel" style="text-error" content="Use link text like “click here” or “learn more”. Link text should be descriptive and inform the user what they are linking to." %}
50 |
51 |
52 |
53 |
54 | To request custom help text, reach out to the [Partner Support Help Desk](https://zendesk.login.gov/).
55 |
56 | [Next step: Add your agency logo]({{ site.baseurl }}/user-experience/agency-logo/)
--------------------------------------------------------------------------------
/_pages/user-experience/knowledge-articles.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: User Experience
3 | lead: >
4 | Create a simple and consistent experience for your Login.gov users
5 | sidenav:
6 | - text: Getting started
7 | href: "user-experience/getting-started/"
8 | - text: Sign-in and sign-out buttons
9 | href: "user-experience/sign-in-sign-out/"
10 | - text: Help text guidance
11 | href: "user-experience/help-text/"
12 | - text: Your agency logo
13 | href: "user-experience/agency-logo/"
14 | - text: Cancel URL
15 | href: "user-experience/cancel-url/"
16 | - text: Failure to proof URL
17 | href: "user-experience/failure-proof/"
18 | - text: Knowledge articles
19 | href: "user-experience/knowledge-articles/"
20 | - text: FAQ content
21 | href: "user-experience/faq-content/"
22 |
23 | ---
24 |
25 | ## Prepare customer support materials
26 |
27 | As you prepare to launch your integration with Login.gov, it is important to consider how your agency will support new users. Here are some suggestions to consider:
28 |
29 | - Announce the upcoming change on your site and include a time frame rather than exact date.
30 | - Link to the [Create an account](https://www.login.gov/create-an-account/){:class="usa-link--external" rel="noreferrer" target="_blank"} page at Login.gov so users can read more about creating an account.
31 | - Include contact information for your help desk or a link to the Login.gov help center () on a dedicated help page.
32 | - Be sure to communicate the go-live date with the Login.gov customer support center so agents are prepared for a spike in new account creation support cases.
33 |
34 | Some partners have created knowledge base articles that they post on their website, send to users directly by the agency’s customer support team, or forward to the Login.gov customer support team. These can be especially helpful if your integration includes any additional authentication steps on your agency's side. Here are some topics for knowledge articles:
35 |
36 | - A brief step-by-step guide to the Login.gov authentication process and the identity verification (IdV) if your agency supports IdV.
37 | - Short description of each requirement in the authentication process, e.g., multi-factor authentication or using a unique email.
38 | - Which support topics should the user contact your agency for help with vs. Login.gov.
39 | - If existing users will need to create a new account or if they will be able to link their agency account to the Login.gov account.
40 |
41 | The Login.gov customer support team can assist users with account creation questions, but they cannot support any agency-specific issues. It is important that users are able to find correct and timely help. Consider including a few support examples along with the link to the Login.gov help center (https://www.login.gov/help/).
42 |
43 | For example:
44 |
45 | {% capture example %}
46 | **Contact Login.gov to:**
47 | - Help you create a Login.gov account
48 | - Share information about authentication options
49 | - Help you troubleshoot why you are unable to access your account
50 | - Provide instructions to reset your password or delete your account
51 |
52 | Login.gov cannot reset your password, delete your account, or change your account information.
53 |
54 | **Contact the agency partner to:**
55 | - Perform agency specific tasks, like uploading your resume, completing applications or scheduling an appointment with that agency
56 | - Resolve technical issues with a partner agency website
57 | - Access your personal agency specific information such as application status, services, eligibility or payments
58 | {% endcapture %}
59 |
60 |
9 | 
42 | 
61 | 
74 | 
83 | ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.
84 | 
102 | Developers
103 | 
41 | 
18 | 
50 | 
62 |