# Creating an OAuth App Eventmaker allows you to setup a [white label](https://en.wikipedia.org/wiki/White-label_product) [Single Sign On (SSO)](https://en.wikipedia.org/wiki/Single_sign-on). ## 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](https://oauth.net/2/). ## 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:///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:///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:///api/v1/me ``` Example using curl: ``` curl -H "Authorization: Bearer " http:///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: . You can test it [here](https://eventmaker-sso-client-demo.herokuapp.com/) (⚠️ 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](https://github.com/oauth-xx/oauth2). ## 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](https://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:///contacts/sign_out ``` Parameters: * redirect\_uri: the URL in your application where users will be sent after sign out. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.eventmaker.io/configuration/creating-an-oauth-app.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.