/authorize endpoint is used to start the social login flow, while the
/authorize/callback endpoint accepts the social provider’s response and then redirects the user back to your application’s authorized callback URI.
The Social Login Flow¶
At a high level, social login involves the following steps:
- The user clicks on a “Login with X” link pointing at the appropriate
- Stormpath handles the login and redirects the user back to your app with a Stormpath Token JWT response
- Your application passes that Stormpath token to the
/oauth/tokenendpoint and receives back OAuth 2.0 access and refresh tokens
If you’d like a more detailed overview:
- User clicks provider-specific link pointing at Client API. This link is returned as part of the login view model retrieved from the
- Your app sends a GET request to the Client API’s
/authorizeendpoint along with
- Client API responds with 302 redirect to appropriate URL at social provider
- Your app sends GET request to redirect URL at social provider
- User logs in to social provider
- Social provider redirects back to Client API’s
/authorize/callbackendpoint along with authorization code
- Client API takes the authorization code and exchanges it with the social provider for a social provider access token, and uses the access token to create/retrieve a user from the Stormpath API.
- Client API constructs a Stormpath assertion JWT, and redirects the user to your app. If no
redirect_uriis specified in the first step, it will be to the first redirect URI in the Application.
- Your app sends the Stormpath assertion JWT to Client API’s /oauth/token endpoint to exchange the assertion JWT for an access/refresh token pair
Before You Start¶
Before you can use Social Login, you must:
- Configure your social provider
- Create a Stormpath Directory for that social provider and map that Directory to your Stormpath Application as an Account Store
Once all of these steps are complete, social login will be ready to go!
1. Configuring Your Social Provider¶
Each social login provider will require you to create an application and configure it in order for login to work. Stormpath offers supports a few specific providers, like Facebook and Google. If you would like to integrate login with a different provider, then you can create a Generic OAuth Directory and configure it for your provider. Example configurations for Generic OAuth Directories can be found in the REST Product Guide.
- Head over to the Facebook App Dashboard: https://developers.facebook.com/apps
- If you haven’t already, create a Facebook app. Instructions for creating a Facebook application can be found here: https://developers.facebook.com/docs/apps/register
- Once you have an application, you should add Facebook Login: https://developers.facebook.com/docs/facebook-login
- Inside the Facebook Login settings, add the full
/authorize/callbackendpoint to the “Valid OAuth redirect URIs” (e.g.
- Head over to the Google Developer Console: https://console.developers.google.com/
- If you haven’t already, create a Google API Console project. Instructions for creating a project can be found here: https://developers.google.com/identity/sign-in/web/devconsole-project
- Inside the OAuth 2.0 client ID settings, add the Client API’s full
/authorize/callbackendpoint to your “Authorized redirect URIs” (e.g.
- If you haven’t already, register a new GitHub OAuth application here: https://github.com/settings/applications/new
- Add the full
/authorize/callbackendpoint under “Authorization callback URL” (e.g.
Initiate Social Login¶
authorize endpoints for all Social Directories associated with your Application are returned as part of the JSON login view model.
The Authorize endpoint takes the following parameters:
||(Required) This specifies what sort of response you would like at the end of this flow. The only possible value currently is
||Valid HREF||(Required) The HREF of a Social Directory associated with your Application.|
||String||(Optional) Any state that you would like to be sent to the provider.|
||Space-delimited String||(Optional) The scopes to request from the Social Provider. The values of these scopes depend on the provider.|
||Valid URI||(Optional) Any URI in the list of Authorized Callback URIs. If you do not include this, the user will be returned to the first entry in this list.|
||1 valid HREF||The HREF of an Organization associated with your Application. This allows you to route the login attempt to a particular Organization.|
||1 valid nameKey||The nameKey of an Organization associated with your Application. This allows you to route the login attempt to a particular Organization.|
GET /authorize?response_type=stormpath_token&account_store_href=https:%2F%2Fdev.i.stormpath.com%2Fv1%2Fdirectories%2F2TRsNjHx8DB6Ca3rBal536 HTTP/1.1 Accept: application/json Host: cold-diver.apps.stormpath.io Connection: close User-Agent: Paw/3.0.13 (Macintosh; OS X/10.12.2) GCDHTTPRequest
As explained above, this will result in a series of 302 redirects that will lead to the social provider’s login page. After the user logs in they will arrive at the URI that was specified in the
redirect_uri parameter, or, if a
redirect_uri was not specified, they will arrive back on the first entry in your Application’s list of Authorized Callback URIs along with a Stormpath Token. At this point, you can exchange this token for OAuth 2.0 access/refresh tokens using the /oauth/token endpoint.