Skip to main content

Create an OAuth Application

Eventmaker allows you to set up a white-label Single Sign-On authentication system.

What is Single Sign-On?

Single Sign-On, or SSO, is an authentication and authorization process that allows users to access multiple services using the same credentials.

Configuring SSO makes Eventmaker the central component of your authentication and authorization system. Eventmaker is particularly well suited for this purpose because it is where your contact data is stored.

When you create a website with Eventmaker, it can easily become a service accessible through your SSO. Your contacts can then sign in to each of your event websites using the same credentials and retrieve data from their previous registrations.

The purpose of this article is to help you delegate the authentication and authorization of your own website, which was not created with Eventmaker, to your Eventmaker-powered SSO.
​

Enable SSO for your Eventmaker account

This feature is not currently available for self-service configuration and must be set up by an Eventmaker administrator.

The result is a sign-in and registration system built on top of your Eventmaker contacts, available on your own domain and using your own branding.

The authorization component of an Eventmaker SSO uses the OAuth 2.0 protocol.

Web application flow

The contact authorization flow for your application works as follows:

  1. From your application, contacts are redirected to your SSO to request access to their identity.

  2. Eventmaker redirects the contacts back to your website.

  3. Your application accesses the Eventmaker API using the contact's access token and retrieves the contact's information.

Register an OAuth application

Before you begin, you must register your application and provide:

  • An application name

  • One or more redirect URLs, used during step 2 of the authorization flow

Once your application has been registered, you will receive an application ID, also referred to as a UID, and a client secret. These credentials are used during the authorization flow.

This step is also currently only available to Eventmaker administrators. Please contact us to register your application.

1. Request access to a contact's Eventmaker identity

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

Parameters

client_id

The unique identifier, or UID, of your application. This value is provided by Eventmaker when your application is registered.

redirect_uri

The URL in your application to which users will be redirected after authorization.

It must exactly match one of the redirect URLs provided when your application was registered.

response_type

Must be set to:

code

scope

Must be set to:

public

This is currently the only available scope.

state

A random, unpredictable string used to protect against Cross-Site Request Forgery attacks.

Your application must store this value and verify it when the user is redirected back to your website.

locale

Optional. Defines the locale initially displayed on the sign-in interface.

Supported values include:

en fr es de pt it

Additional languages supported by Eventmaker may also be available.

Users can change the language from the sign-in interface.

Example

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

This request asks the contact to authenticate through your SSO and authorize your application to access their data.

2. Users are redirected back to your website

If the contact approves your request, the SSO redirects them to your website with:

  • A temporary authorization code in the code parameter

  • The value provided during the previous step in the state parameter

Your application must compare the returned state value with the one stored before the authorization request.

If the values do not match, the request may have been created by a third party and the authorization process must be stopped.

Exchange the temporary authorization code for an access token using the following request:

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

Parameters

client_id

The unique identifier, or UID, of your application. This value is provided by Eventmaker when your application is registered.

client_secret

The client secret of your application. This value is provided by Eventmaker when your application is registered.

code

The temporary authorization code received after step 1.

redirect_uri

The URL in your application to which users are redirected after authorization.

This value must match the redirect_uri used in the authorization request.

code_verifier

A random, unpredictable string used by the Proof Key for Code Exchange mechanism.

grant_type

Must be set to:

authorization_code

JSON response

{
   "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 your application to send API requests on behalf of the contact.

Include the token in the Authorization header:

Authorization: Bearer OAUTH_TOKEN

Then call the following endpoint:

GET https://<sso-domain>/api/v1/me

cURL example

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

This API request returns the contact's information, including:

  • Email address

  • First name

  • Last name

  • Any additional fields configured in Eventmaker

Example application

We have created a Ruby and Sinatra example application that uses an Eventmaker-powered SSO:

https://github.com/applidget/eventmaker-sso-client-demo

Review the source code to see how the authorization flow described above can be implemented.

A library is probably available to help you implement this integration in your preferred programming language.

The example application uses the oauth2 Ruby gem.
​

Local development

The OAuth protocol requires secure endpoints for both the provider and the client.

You therefore need an HTTPS server running on your local machine.

You can use a secure tunnelling service to expose your local development server to the internet through an HTTPS endpoint.

Make sure that the HTTPS callback URL generated by the tunnelling service is registered as one of your application's authorized redirect URLs.
​

Manage sign-out

When a contact signs out of your application, they remain signed in to the SSO.

As a result, signing in again may automatically trigger the successful authorization callback and immediately sign the contact back into your application.

To also sign the contact out of the SSO, use the following endpoint:

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

Parameter

redirect_url

The URL in your application to which the contact will be redirected after signing out.

Example

GET https://<sso-domain>/contacts/sign_out?redirect_url=https%3A%2F%2Fmy-app.com
Related Articles
Did this answer your question?