Overview

This document provides technical specifications for authenticating profiles via the membes Single Sign On (SSO).

Via login from third party software

Use this process for a link from third party software to a login form where user is authenticated with both membes and third party software.

Prerequisites

1. membes API

   1. The membes API incurs a setup and ongoing fee (provided on request), the customer can request access by logging a ticket in the Help Desk or emailing support@membes.com.au.

2. API Keys and ClientID

   1. membes will provide the API keys and ClientID after the API has been enabled.

3. Callback URL

   1. To be provided to membes by the third party software provider.

   2. Email the callback URL to support@membes.com.au.

SSO Process

1. Request SSO Form (login form)

   1. https://[website_url]/member/oauthlogin/?redirect_uri=http://callbackurl&client_id=[client_id]&state=[callback_state]

   2. This call will respond with a login form.

2. On Submission of SSO form

   1. User is authenticated with membes AMS.

   2. User is directed to [callback_url].

3. Callback to [callback_url] will contain the following parameters

   1. ?code=[access_token]

   2. &state=[callback_state]

Refresh token

Access token is valid for one hour. Optionally, a refresh token can be obtained from the membes API.

1. https://api.membes.com.au/api/oauth2/?refresh_token=[refreshtoken]

2. Response: { status: true, "access_token": "xxxx-xxxx-xxxx" }

Membes API

Once access token has been obtained, further information about the authenticated user can be obtained from the membes API.

To request access token for the API:

1. https://api.membes.com.au/api/oauth2/?code=[callback_token]&client_secret=[client_secret]

2. Response: { status: true, "access_token": "xxx-xxx-xxx-xxx", "refresh_token": "yyy-yyy-yyy"}

Access third party software via link on website

Use this process if you want to provide a link to the third party software from a user already logged into their membes website.

Prerequisites

1. Membes API

   1. The membes API incurs a setup and ongoing fee (provided on request), the customer can request access by logging a ticket in the Help Desk or emailing support@membes.com.au.

2. API Keys and ClientID

   1. membes will provide the API keys [apikey] and ClientID [clientid] after the API has been enabled.

3. API Url

   1. The URL for the membes customer API. [membesapiurl]

Creating the Link in website

1. Login to membes admin > CMS.

2. Navigate to the page that you want to place the link to the 3^rd party software in.

3. Make sure the page is set to require login, as the user must be logged in for the Authenticated URL to be generated.

4. In the href parameter of the link, place the following shortcode:

   [code]Application.util.authLink("www.yoursite.com")[/code]

This shortcode, when rendered, will generate a url containing a JWT Token as a url parameter called “membes_token”.

e.g. http://yoursite/?membes_token=[jwttoken]

When the logged in user clicks the generated link they will be sent to “http://yoursite” with the token appended to the URL.

Validating the Token

When you receive a request to http://yoursite with membes_token in the URL, you then validate this token via the membes API at [membesapiurl].

1. Send token to GET: http://[membesapiurl]/api/token/validate/[jwttoken]

2. Response will be JSON format:

{ 
  valid: true|false,
  data: {
    id: [membes PK],
    profileNumber: [profileNumber],
    firstName: [first name],
    surname: [surname],
    email: [primary email address],
    membershipType: [membership type as string],
    membershipTypeID: [membership type as ID],
    membershipStatus: [membership status as string (--, Active, Inactive) ],
    membershipStatusID: [membership status as ID],
  }
}