Creating an OAuth App

Eventmaker allows you to setup a white label Single Sign On (SSO).

What is a SSO ?

SSO is an authentication / authorization flow through which a user can log into multiple services using the same credentials. Setting up a SSO make Eventmaker the main component for your authentication / authorisation system. We believe it's the perfect place since Eventmaker is where data of your contacts are stored.

When you build a website with Eventmaker it can easily become a service accessible through your SSO. Hence your contacts can connect to the websites of each one of your events using the same credentials and get back all their data of their previous registration(s).

The goal of this article is to get you started delegating the authentication and authorization of your own website (not one built with Eventmaker) to your Eventmaker powered SSO.

Enabling the SSO of your Eventmaker account

This part is not accessible yet and must be configured by an Eventmaker admin. The outputs is a sign-in / register system on top of your Eventmaker contacts, that is accessible on your own domain and with your own branding. The authorisation part of an Eventmaker SSO use the OAuth 2 protocol.

Web application flow

The flow to authorize contacts for your app is:

• 1️⃣From your app, contacts are redirected to request their identity on your SSO

• 2️⃣Contacts are redirected back to your site by Eventmaker

• 3️⃣You app accesses the Eventmaker API with the contact's access token and get back the contact data

Registering an OAuth app

Before starting, you must register your app and provide a name and one or more redirection URLs (used in step 2 of the flow). Once done, you will get an application UID and a secret that will be used during the authorization flow.

This step is also only available to Eventmaker admins for now, so please contact us 😊.

1. Request one of your Eventmaker contact identity

GET https://<sso-domain>/oauth/authorize

Parameters:

• client_id: the UID of your app you received from Eventmaker when you registered your app.

• redirect_uri: the URL in your application where users will be sent after authorization. Must matches with one of the redirection URLs used when you registered your app.

• response_type: code

• scope: public (the only scope currently available)

• state: an unguessable random string. It is used to protect against cross-site request forgery attacks.

• locale: optional, the locale to use (en, fr, es, de, pt, it + potential new languages supported by Eventmaker). The user will be able to change it once on the sign in interface.

Example:

http://my-sso.com/oauth/authorize?client_id=ccd2524cf6d3e8feb457dd912cd73f07c80a311875bb3fb0c776a29301626bc0&redirect_uri=https%3A%2F%2Fmy-app.com%2Fauth%2Foauth%2Fcallbac&scope=public&state=b6c7d807b564af9e63da5ce1484403d9

This will ask the contact to authenticate on your SSO and allow your app to access his data.

2. Users are redirected back to your site

If the contact accepts your request, your SSO redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don't match, then a third party created the request, and you should abort the process.

Exchange this code for an access token:

POST https://<sso-domain>/oauth/token

Parameters:

• client_id: the UID of your app you received from Eventmaker when you registered your app.

• client_secret: the secret of your app you received from Eventmaker when you registered your app.

• code: the code you received as a response to step 1️⃣.

• redirect_uri: the URL in your application where users will be sent after authorization.

• code_verifier: an unguessable random string

• grant_type: authorization_code

Response (JSON):

{
   "access_token": "d77f57f68cef725e2dba1fd106e237f027283c42f583c13bf308c65426fe51ab",
   "token_type": "Bearer",
   "expires_in": 7200,
   "scope": "public",
   "created_at": 1558633788
}

3. Use the access token to access the API

The access token allows you to make requests to the API on behalf of a contact.

Authorization: Bearer OAUTH-TOKEN
GET https://<sso-domain>/api/v1/me

Example using curl:

curl -H "Authorization: Bearer <token>" http://<sso-domain>/api/v1/me.json

This API call will provide contact data (email, first_name, last_name and all the fields you defined in Eventmaker).

Sample application

We have setup a sample Ruby/Sinatra application that uses an Eventmaker powered SSO: https://github.com/applidget/eventmaker-sso-client-demo. You can test it here (⚠️ free Heroku app, might take a few seconds to wake up). Read the sources to see how everything discussed previously can be implemented.

Note that there is probably an existing library to help you with this integration in your language. In the sample app we are using the oauth2 gem.

Working locally

The OAuth protocol requires secure endpoints (for the provider and the client), you will then need to have an HTTPS server running on your computer. The easiest way to achieve this is to use serveo.net. This will allow you to expose in one command line your locally running server to the internet and get a secure endpoint with it.

Handling sign out

When signing out, the contact will always be signed in on the SSO, so signing-in again will automatically trigger the success callback and the contact will be automatically connected. To trigger a sign out from the SSO :

GET https://<sso-domain>/contacts/sign_out

Parameters:

• redirect_uri: the URL in your application where users will be sent after sign out.