Single sign-on service

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.

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.

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.

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 obtain 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:

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:

• Web browser
  The browser being used by the Wild Apricot user
• Client application
  The external site that you want to integrate with your Wild Apricot account
• Association website
  Your Wild Apricot website
• oAuth service
  The OAuth authentication service
• WA public API
  Wild 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:

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 :
   
   client_id
   The identifier of the client application. Obtained when you register the external site as an authorized application.
   
   redirect_uri
   URL 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. Currently, any other scope value will result in an error.
   
   state
   Optional 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:

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:

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:
   
   grant_type
   Should be set to authorization_code.
   
   code
   The authorization code returned by Wild Apricot's single sign-on service.
   
   client_id
   The identifier of the client application. Obtained when you register the external site as an authorized application.
   
   redirect_uri
   Must 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.)
   
   scope
   Must match the scope specified in the initial Wild Apricot authentication request.
3. 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:
   POST https://oauth.wildapricot.org/auth/token
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9wYXNzd29yZA== grant_type=authorization_code&code=09827394752790347&client_id=CLIENT_ID&redirect_uri=http://callback.yourdomain.com&scope=contacts_me
4. 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.

Open source authentication plugins

There are third-party, open source plugins available for authenticating access to Wild Apricot sites. For more information, click the following links:

• Open source Wild Apricot authentication plugin for Discourse
• Open source Wild Apricot authentication plugin for Joomla

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:

1. The external site sends a POST request to /sys/login/logoutnonce on their Wild Apricot site. The request should include the following parameters:
   
   token
   Valid oAuth token
   
   email
   Email 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.