• Overview
• Authorizing external applications
• How SSO works
• Requesting WildApricot authentication
• Authenticating the user
• Authorization token request
• Logging out from single sign-on
Overview
Using WildApricot's single sign-on service (SSO), you can integrate an external website with your WildApricot site. With SSO implemented, your members can log in to both sites using their WildApricot credentials.
All interactions between external applications and WildApricot accounts use WildApricot's API.
Important Note: WildApricot's SSO service uses secure access via HTTPS. Custom domains without SSL certificates will encounter problems integrating WildApricot with other sites.
Authorizing external applications
All external sites that access WildApricot's API must be registered in your account as an authorized application. For instructions, see Authorizing external applications.
How SSO works
Calls to WildApricot's API must include an authentication token that authenticates your WildApricot account and prevents others from accessing your data. Requests for authentication tokens are sent to an OAuth server.
With SSO, an authentication token is obtained in the following manner:
1. A WildApricot user clicks the Login button for single sign-on.
2. An external site redirects the browser to WildApricot's SSO form.
3. The WildApricot 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 in the diagram above:
- Web browser
The browser being used by the WildApricot user - Client application
The external site that you want to integrate with your WildApricot account - Association website
Your WildApricot website - OAuth service
The OAuth authentication service - WA public API
WildApricot's API
Requesting WildApricot authentication
The first stage in the process of obtaining an authentication token is initiated when the WildApricot user attempts to view content that requires WildApricot authentication. This stage involves the following steps:
- The WildApricot 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 yourWildApricotSite is the unique URL of your WildApricot 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. Any other scope value will result in an error.
state
Optional parameter. This can be any value you need to track the request.
Authenticating the user
The next stage is authenticating the WildApricot user. This involves the following steps:
- The browser follows the redirect to WildApricot's SSO screen.
- If the query string parameters are valid, the screen is displayed to the user.
- On WildApricot's SSO screen, the WildApricot user enters their username and password.
- The SSO 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 code and state values as query string arguments.
Authentication token request
The final stage is the authentication token request, and involves the following steps:
- The browser follows the redirect from the SSO 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:
- grant_type
Should be set to authorization_code - code
The authorization code returned by WildApricot's SSO 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 WildApricot authentication request - scope
Must match the scope specified in the initial WildApricot authentication request
- grant_type
- 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 - The OAuth service returns the authentication token in JSON format. The token can now be used in WildApricot .
Want to dive deeper? See Using WildApricot's API and API Authentication
Logging out from single sign-on
To log out a user from the external site and their WildApricot account, the external site takes the following steps:
- The external site sends a POST request to /sys/login/logoutnonce on their WildApricot site. The request should include the following parameters:
- token
Valid OAuth token - email
Email address of logged-in user - redirectUrl
URL to which the user will be redirected after logging out
- token
- The WildApricot site returns a JSON structure with a one-time nonce code.
- The external site redirects the user to /sys/login/logout on their WildApricot site and includes the nonce code in request as a query string parameter.
- The WildApricot site checks the nonce code, removes the authentication cookie, and redirects the user to the specified redirectUrl.