Home

Download this help site
(PDF 82MB)

Download

Single sign-on service

Icon

Wild Apricot's single sign-on service is intended for use by developers with technical expertise. If you need assistance, we provide support via email or through our Developers forum.

Using Wild Apricot's single sign-on service, you can integrate an external site – like your Joomla or Drupal site – with your Wild Apricot site. With single sign-on implemented, your members can log into both sites using their Wild Apricot credentials, and you can restrict content on your external site to Wild Apricot members.

The single sign-on service was initially developed to support integration with WordPress, but can be used with any site that supports server-side code.

All interactions between external applications and Wild Apricot accounts take place using Wild Apricot's API.

Icon

Wild Apricot's single sign-on service uses secure access via HTTPS. Custom domains without SSL certificates will encounter problems integrating Wild Apricot with other sites. You can either purchase a SSL certificate or set your wildapricot.org domain as your primary domain.

Authorizing external applications

All external sites that access Wild Apricot's API must be registered as an authorized application. For instructions, see Authorizing external applications.

Obtaining an authentication token

Calls to Wild Apricot's API must include an authentication token that authenticates your Wild Apricot account and prevents others from accessing your data. Requests for authentication tokens are sent to an OAuth server.

Within the single sign-on scenario, an authentication token is obtained in the following manner:

 Read more/less
  1. A Wild Apricot user clicks the Login button for single sign-on.
  2. An external site redirects the browser to Wild Apricot's single sign-on form.
  3. The Wild Apricot user enters their credentials and clicks the Login button.
  4. If the user's credentials are authenticated, the form returns an authorization code.
  5. The authorization code is used to request an authentication token from oAuth.
  6. If the request is valid, oAuth returns an authentication token.

These steps are illustrated in the following diagram and described in more detail below.

The following roles appear on the diagram:

RoleDescription
Web browserThe browser being used by the Wild Apricot user
Client applicationThe external site that you want to integrate with your Wild Apricot account
Association websiteYour Wild Apricot website
oAuth serviceThe OAuth authentication service
WA public APIWild Apricot's API

Requesting Wild Apricot authentication

The first stage in the process of obtaining an authentication token is initiated when the Wild Apricot user attempts to view content that requires Wild Apricot authentication. This stage involves the following steps:

 Read more/less
  1. The Wild Apricot user accesses a page with restricted content and is prompted to log in.
  2. The external site builds a URL and returns a HTTP 302 Redirect to  https://yourWildApricotsite/sys/login/OAuthLogin where https://yourWildApricotsite  is the URL of your Wild Apricot site The following parameters should be passed as query string arguments :

    ParameterDescription
    client_idThe identifier of the client application. Obtained when you register the external site as an authorized application.
    redirect_uriURL to which the user will be redirected after login. The URL you specify must be included in the Trusted redirect domains list within the authorized application details.
    scope

    Should be set to contacts_me.

    Icon

    Currently, any other scope value will result in an error.

    stateOptional parameter: any value you need to track the request.

Authenticating the user

The next stage is authenticating the Wild Apricot user, and involves the following steps:

 Read more/less
  1. The browser follows the redirect to Wild Apricot's single sign-on screen.
  2. If the query string parameters are valid, the screen is displayed to the user.
  3. On Wild Apricot's single sign-on screen, the Wild Apricot user enters their username and password.
  4. The single sign-on service checks the user's credentials.

  5. If the credentials are valid, the service sets the authentication cookie, builds an URL, and returns a HTTP 302 Redirect. The URL is based on the redirect_uri parameter specified above, and includes authorization_code and state values as query string arguments.

Requesting the authentication token

The final stage is the authentication token request, and involves the following steps:  

 Read more/less
  1. The browser follows the redirect from the single sign-on service.
  2. The external site requests an authentication token from the oAuth service.  The following parameters should be passed in the POST request with content type set to application/x-www-form-urlencoded:

    Parameter Description
    grant_typeShould be set to authorization_code.
    codeThe authorization code returned by Wild Apricot's single sign-on service.
    client_idThe identifier of the client application. Obtained when you register the external site as an authorized application.
    redirect_uriMust match the URL specified in the initial Wild Apricot authentication request. (This is done to double check the URL and prevent the request from being hijacked.)
    scopeMust match the URL specified in the initial Wild Apricot authentication request.

    The client_id and client_secret should be passed in the authorization header, delimited by colon and base64 encoded. The authorization scheme is Basic.

    Example

     

  3. The oAuth service returns the authentication token in JSON format. The token can now be used in Wild Apricot API calls. For more information on the authentication response, click here.

Logging out from single sign-on

To log out a user from the external site and their Wild Apricot account, the external site must take the following steps:  

 Read more/less
  1. The external site sends a POST request to /sys/login/logoutnonce on their Wild Apricot site. The request should include the following parameters:

    ParameterDescription
    tokenValid oAuth token
    emailEmail of logged in user

    redirectUrl

    URL to which the user will be redirected after logging out
  2. The Wild Apricot site returns a JSON structure with a one-time nonce code.
  3. The external site redirects the user to /sys/login/logout on their Wild Apricot site and includes the nonce code in request as a query string parameter.. 
  4. The Wild Apricot site checks the nonce code, removes the authentication cookie, and redirects the user to the specified redirectUrl. 

On this page: 

See also:

  • No labels