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.
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.
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:
- A Wild Apricot user clicks the Login button for single sign-on.
- An external site redirects the browser to Wild Apricot's single sign-on form.
- The Wild Apricot user enters their credentials and clicks the Login button.
- If the user's credentials are authenticated, the form returns an authorization code.
- The authorization code is used to request an authentication token from oAuth.
- 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:
- The Wild Apricot user accesses a page with restricted content and is prompted to log in.
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 :
Parameter Description 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.
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:
- The browser follows the redirect to Wild Apricot's single sign-on screen.
- If the query string parameters are valid, the screen is displayed to the user.
- On Wild Apricot's single sign-on screen, the Wild Apricot user enters their username and password.
The single sign-on service checks the user's credentials.
- 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:
- The browser follows the redirect from the single sign-on service.
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_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 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.
- 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:
The external site sends a POST request to /sys/login/logoutnonce on their Wild Apricot site. The request should include the following parameters:
Parameter Description token Valid oAuth token Email of logged in user
URL to which the user will be redirected after logging out
- The Wild Apricot site returns a JSON structure with a one-time nonce code.
- 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..
- The Wild Apricot site checks the nonce code, removes the authentication cookie, and redirects the user to the specified redirectUrl.