Single sign-on service (SSO)

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:

  1. The WildApricot 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 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:

  1. The browser follows the redirect to WildApricot's SSO screen.
  2. If the query string parameters are valid, the screen is displayed to the user.
  3. On WildApricot's SSO screen, the WildApricot user enters their username and password.
  4. The SSO 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 code and state values as query string arguments.

Authentication token request

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

  1. The browser follows the redirect from the SSO 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:
      1. grant_type
        Should be set to authorization_code
      2. code
        The authorization code returned by WildApricot's SSO service
      3. client_id
        The identifier of the client application. Obtained when you register the external site as an authorized application.
      4. redirect_uri
        Must match the URL specified in the initial WildApricot authentication request
      5. scope
        Must match the scope specified in the initial WildApricot 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 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:

  1. The external site sends a POST request to /sys/login/logoutnonce on their WildApricot site. The request should include the following parameters:
      1. token
        Valid OAuth token
      2. email
        Email address of logged-in user
      3. redirectUrl
        URL to which the user will be redirected after logging out
  2. The WildApricot site returns a JSON structure with a one-time nonce code.
  3. 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.
  4. The WildApricot site checks the nonce code, removes the authentication cookie, and redirects the user to the specified redirectUrl.


Search: WildApricot.com 

About results ( seconds) Sort by: 
Sorry, an error occured when performing search.
Powered by Zendesk