On this page
Add a social Identity Provider
This document explains how to configure
Okta manages the connection to the IdP for your application, sitting between your application and the IdP that authenticates your users. The industry-standard term for this is Inbound Federation. When a user signs in, you can link the user’s
Note: We also support additional services such as directories and credential providers. See the Okta Integration Network Catalog (opens new window) to browse all integrations by use case.
Learning outcomes
Configure a social Identity Provider so that your users can quickly sign up or sign in to your application by using their social Identity Provider account.
What you need
- Okta Developer Edition organization (opens new window)
- An OpenID Connect (OIDC) app integration in Okta. You can create a new OIDC app integration using AIW (opens new window) or use an existing one.
- An account with
Create an app at the Identity Provider
When you create an application at the IdP, you need to provide a redirect URI for authentication.
The redirect URI sent in the authorize request from the client needs to match the redirect URI set at the IdP. This URI is where the IdP sends the authentication response (the access token and the ID token). It needs to be a secure domain that you own. This URI has the same structure for most IdPs in Okta and is constructed using your Okta subdomain and the callback endpoint.
For example, if your Okta subdomain is called
company
, then the URI would behttps://company.okta.com/oauth2/v1/authorize/callback
. If you have configured a custom domain in your Okta org, use that value to construct your redirect URI, such ashttps://login.company.com/oauth2/v1/authorize/callback
.Save the generated
GitHub
Create the Identity Provider in Okta
To add
GitHub
In the Admin Console, go to Security > Identity Providers.
Click Add Identity Provider, and then select
GitHub
Click Next.
In the General Settings section, define the following:
- Name: Enter a name for the Identity Provider in Okta.
- Client ID: Paste the generated client ID from your
GitHub
- Client Secret: Paste the generated client secret from your
GitHub
- Scopes: Leave the defaults for a simple sign-in flow. You can also add more scopes. See .
Click Finish.
Test the integration
You can test your integration by configuring a routing rule (opens new window) to use
GitHub
Alternatively, you can use the Authorize URL to simulate the authorization flow. The Okta Identity Provider that you created generated an authorize URL with a number of blank parameters that you can fill in to test the flow with the Identity Provider. The authorize URL initiates the authorization flow that authenticates the user with the Identity Provider.
In the URL, replace ${yourOktaDomain}
with your org's base URL, and then replace the following values:
client_id
: Use theclient_id
value from your Okta app integration. This is not theclient_id
from the Identity Provider. For example,0oawjqpb2wcUAWM8C0h7
.response_type
: Determines which flow is used. For the Implicit flow, useid_token
. For the Authorization Code flow, usecode
.response_mode
: Determines how the authorization response is returned. Usefragment
.scope
: Determines the claims that are returned in the ID token. Include the scopes that you want to request authorization for and separate each with a%20
(space character). You need to include at least theopenid
scope. You can request any of the standard OpenID Connect scopes about users, such asprofile
andemail
as well as any custom scopes specific to your Identity Provider.redirect_uri
: The location where Okta returns a browser after the user finishes authenticating with their Identity Provider. This URL must start withhttps
and must match one of the redirect URIs that you configured in the previous section.state
: Protects against cross-site request forgery (CSRF). This can be set to any value.nonce
: A string included in the returned ID token. Use it to associate a client session with an ID token and to mitigate replay attacks. This can be set to any value.
For a full explanation of all of these parameters, see: /authorize Request parameters.
An example of a complete URL looks like this:
https://${yourOktaDomain}/oauth2/v1/authorize?idp=${idp_id}&client_id=${client_id}&response_type=id_token&response_mode=fragment&scope=openid%20email&redirect_uri=https%3A%2F%2FyourAppUrlHere.com%2F&state=WM6D&nonce=YsG76jo
Handle users without email addresses
GitHub doesn’t always provide email addresses for users that it authenticates, such as when the GitHub setting Keep email addresses private is enabled. However, Okta requires an email address for its users to be able to sign in. You can support users who don't have email addresses by using information from GitHub to generate email addresses for them.
For example, you might generate email addresses using the example.com
domain. This ensures that your GitHub users have email addresses that Okta can use, but can be easily identified as invalid should you ever want to replace them with valid email addresses. They're guaranteed to be invalid as example.com
is a reserved domain. See Reserved Top Level DNS Names (RFC2606) (opens new window) for more information on reserved domains.
You can customize this mapping by using the Okta Expression Language. See Profile Editor (opens new window) for more information on attribute mapping.
To generate user login values and email addresses for GitHub users, do the following:
From the Admin Console, click Security.
Click Identity Providers.
Locate GitHub in the list of providers, then click Configure > Edit Profile and Mappings.
Click Mappings.
Select the tab that maps a GitHub user to an Okta user.
Set the expression that maps to the Okta user's
login
value to:appuser.email == null ? appuser.externalId + '@github.example.com' : appuser.email
Set the expression that maps to the Okta user's
email
value to:appuser.email == null ? appuser.externalId + '@github.example.com' : appuser.email
Click Save Mappings
Similarly, you can map the IdP username by doing the following:
From the Admin Console, click Security.
Click Identity Providers.
Locate GitHub in the list of providers, and then click Configure > Configure Identity Provider.
Set the expression for IdP Username to:
idpuser.email == null ? idpuser.externalId + '@github.example.com' : idpuser.email
Click Update Identity Provider
Add the Identity Provider to the Okta Sign-In Widget
Note: This section is only for Okta Classic Engine. If you are using Okta Identity Engine, the Sign in with IdP option is available on the widget after you've created the Identity Provider in your Okta org and configured the routing rule (opens new window). No additional code is required. See Identify your Okta solution (opens new window) to determine your Okta version and see Upgrade your widget for upgrade considerations to Identity Engine.
The Okta Sign-In Widget (opens new window) is an embeddable JavaScript widget that reproduces the look and behavior of the standard Okta sign-in page. You can add a Sign in with GitHubYour_IDP_ID
with the Identity Provider ID from your Identity Provider that you created in Okta in the Create the Identity Provider in Okta section.
To find your Identity Provider ID:
- In the Admin console, go to Security > Identity Providers.
- On the Identity Providers page, select the Identity Provider tab.
- Select your Identity Provider from the list. IdP ID contains your Identity Provider ID.
config.idps= [
{ type: 'GITHUB', id: 'Your_IDP_ID' }
];
config.idpDisplay = "SECONDARY";
Next steps
You should now understand how to add a social Identity Provider and have successfully added and tested the integration.
To map Okta attributes to app attributes, use the Profile Editor (opens new window).
To add another Identity Provider, start by choosing an external Identity Provider.