Federated Authentication

Currently, mitter.io supports only OAuth as a federated authentication mechanism and we are slowly rolling out the features, we currently only support Google as the OAuth provider. Soon, we will be rolling out multiple provider support out of the box and also the ability to use any arbitrary OAuth provider for authentication.

To set up Google Federated Authentication, you need to first to get OAuth credentials from Google. To do so,

1. Go to the Google Developer Console API Credentials page and

   select your project from the menu on the top-bar.

2. Click on Create Credentials and select OAuth Client Id.

3. In the next page select Web Application.

4. Use any name you want for the credential. In the Authorized redirect URIs enter the URI from the mitter.io subscriber panel. To do so, go to the subscriber panel and go to Hosted Services. Under the Google Authentication Service tile, there will be a field called Google Redirect URI. Copy the value shown here.

   

5. Save the credential. When you do so, Google will display a Client Id and a Client Secret. Keep this available with you.

6. Go back to the Subscriber UI and go to Properties. Go to New Property > Google > Credentials > OAuth Credentials.

7. In the dialog that shows up, enter the values that you got from the Google Developer console.

8. The instance-name is for your record-keeping purposes, so you can use anything you want. The project number and the application name does not matter for OAuth, but it is recommended you use the project number and the application name the same as that of your Google project.

9. Save these details.

So far, this is the setup:

1. Mitter now provides a URI that you can use for sending your users to the Google OAuth page. This directly links to the Google OAuth service.

2. Google on authenticating the service, will forward the user to a mitter.io hosted page, where mitter will create a new user (or link an existing user using the email) and verify the tokens with Google.

3. Mitter will automatically log-in the user, and generate a user authentication token for the user.

However, currently, mitter cannot communicate with your application about all these operations. To allow it to do so, go to the subscriber panel, Properties tab and go to New Property > Mitter > OAuth Integration. Enter the following information:

1. *instance-name' This can be anything you prefer, it is for your record-keeping purposes.

2. OAuth redirect URI The URI mitter should redirect you to once it verifies with the authenticating service (in this case, Google) or in the case of an error.

3. require state signing This feature is currently not supported, but when in use, mitter will only accept

   authentication requests which need to be signed using one of the issued access keys. If this is selected, no frontend client can make authentication requests without a backend, as they would not be in possession of an access key for the application.

Once all these steps are done, the Google Authentication service in the Hosted Services panel will show up as ACTIVE.

To test it once, visit the URI shown in Google OAuth endpoint and the Google authentication service should show up, you should be able to log-in and be redirect to the URI you provided.

Accessing the Federated Authentication parameters

When the user is redirected to the URI as entered in the OAuth Integration config, the following query parameters are sent with it:

1. federatingService The service used to authenticate the service. In this case, it will always be

   GoogleFederationService.

2. linkCandidates The candidates found for auto-linking to the user. If there are multiple users, no user will be linked, and your app must make the decision of which user to link (generally by user input) using the linking API. For the GoogleFederatingService, there is guaranteed to be exactly one user in this list.

3. autoLoginToken If the user was logged in, a token that can be used to authenticate the user.

4. federatedUserId An identifier used to identify the federated user. This is NOT THE SAME as the user id.

5. linkedUser The user id of the user which is linked to this federated user.

6. externalServiceTokens The tokens returned by the federating service. In the case of google authentication service, this will contain the access token as provided by Google. If state signing is used, the refresh token will also be given. Both tokens will be delimited by a comma (,).