Member Authentication Tutorial

In order to authenticate a member with their credentials, you must use the standard OAuth 2.0 Authorization Code Flow. This process involves you sending your users to a Daxko login form, and we will redirect back to your site with an authorization code that can be used to make server to server API calls.

Step 1: Settings (one-time setup)

You must first configure settings to enable the authentication form for your username before using the form using the members-settings API call.

• valid_redirect_uris is a required list of URLs on your site that Daxko can redirect to after a successful authentication of a member.
• If you enter a non-blank value for links.sign_up.url and links.forgot_password.url, then we will render a link on our form that links to your site so that you can handle the sign up and/or forgot password flow and control that experience.

Request:

PUT /v1/partners/oauth2/members/settings
{
      "valid_redirect_uris": [
      "https://www.example.com/successful_login"
    ],
    "links": {
      "sign_up": {
        "url": "https://www.example.com/my_sign_up_process"
      },
      "forgot_password": {
        "url": "https://www.example.com/my_forgot_password_process"
      }
    }
}

NOTE: If you set the links.forgot_password.url value to null or an empty string, the built-in forgot-password flow for Daxko Operations Online will be used.

Step 2: Build Auth Form URL

In your code, build a URL using the format below, which will redirect your user to Daxko Operations:

https://operations.oauth2.partners.daxko.com/authorize
  ?response_type=code
  &scope=clientIntegrationId%3AOPS_9991
  &state=axjfoa83alksdfj
  &client_id=my_api_username
  &redirect_uri=https://www.example.com/successful_login

Explanation of parameters:

• response_type=code - This tells Daxko that your application is initiating the authorization code flow.
• client_id - The API username provided by Daxko. This is the standard parameter name specified by OAuth — do not confuse this with the ID of the client you are request access for.
• redirect_uri - Tells Daxko where to send the user back to after the request is approved. NOTE: This must be configured first in Step 1.
• scope - This indicates the client you are requesting access for. clientIntegrationId:NNNN says that you're requesting a login for for Daxko Operations client 9111 where NNNN is the client ID you have been provided as part of your integration registration, such as OPS_9991.
• state - Your application generates a random string and includes it in the request. You should then check that the same value is returned after the user authorizes the app. This is used to prevent CSRF attacks as well as to optionally pass metadata throughout the OAuth process.

NOTE: If your application is requesting access to be able to log in to Daxko Operations automatically on behalf of the user, you must also pass an additional scope of memberAutoLogin:get to the initial authentication request, so the authentication flow knows you are requesting an access token that can be used in a magic link. If your credentials have not been granted those permissions, please contact Daxko's API support to address the scope-permissions issue. Your scope query-string parameter request would then look as follows: scope=clientIntegrationId%3AOPS_9991%20memberAutoLogin%3Aget (do note that the : character is escaped as %3A and a space as %20).

When users reaches this page, they will be shown a login screen.

Step 3: Redirect Back to Your Site

When the login is successful, you will redirect back to your site (using the redirect_uri specified in Step 2, along with additional parameters in the URL.

Daxko Operations redirects the user to:

https://www.example.com/successful_login
  ?code=haOFJDr87EaP0d0tllfL0MHsVfIvJTHaOPPaTbixRXw
  &state=axjfoa83alksdfj

The code expires in 10 minutes. You should validate that the state value is the same value that you passed in Step 2 and throw an error on your site if they don't match (this protects against Cross-site request forgery attacks).

Step 4: Exchange Auth Code for Access Token

Use the code from Step 3 value to make a secure API call from your server (where the API credentials are securely stored) to get an access_token for this member.

You need to make an API call to https://operations.oauth2.partners.daxko.com/token using these parameters:

An example curl request to get an access token for this member would be:

curl -XPOST https://operations.oauth2.partners.daxko.com/token \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "authorization_code",
    "client_id": "daxko_api_user",
    "client_secret": "d9a2652cf96d734661c10d5ff2f8061f",
    "code": "haOFJDr87EaP0d0tllfL0MHsVfIvJTHaOPPaTbixRXw",
    "redirect_uri": "https://www.example.com/successful_login"
}'

Response:

{
  "access_token": "ayJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...",
  "refresh_token": "6848c0ec2ca91aa444651d9166dc518c09a5f19234",
  "expires_in": "600",
  "token_type": "bearer"
}

This access token expires in 10 minutes. Once you exchange the code for the access token, the code will no longer be valid. The refresh token expires in 90 days, when the user changes their password or when the refresh token is revoked for security reasons. You should store this refresh token per user in your application, so that you can use it later to generate a fresh access token for the auto-login magic link.

Step 5: Refreshing your token

Refresh tokens provide the ability to generate a new access token for your member without the need to prompt them for their credentials again. The flow is similar to the last step of the OAuth2 flow, but with a few small differences:

• You must pass a grant_type value of refresh_token.
• You must pass the refresh_token value.
• You need not provide a code or a redirect_uri.

curl -XPOST https://operations.oauth2.partners.daxko.com/token \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "refresh_token",
"client_id": "daxko_api_user",
"client_secret": "d9a2652cf96d734661c10d5ff2f8061f",
"refresh_token": "6848c0ec2ca91aa444651d9166dc518c09a5f19234"
}'

The response is as follows, and please do note that you will not receive a new refresh token for this call but will instead need to continue using your originally-provided one:

{
  "access_token": "ayJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...",
  "expires_in": "600",
  "token_type": "bearer"
}

Step 6: Get Member Info

You now have an access_token that is scoped to this member. The only call you currently make with this access_token is /members/me using the access_token value in the header such as: Bearer ayJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...

curl -XGET https://api.partners.daxko.com/api/v1/members/me \
-H "Authorization: Bearer ayJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ..."

Response:

{
  "member_id": "400007995-00",
  "member_unit_id": "400007995",
  "name": {
    "first_name": "Erika",
    "last_name": "Doe"
  }
}

Now that you have member_id and member_unit_id, you can use these IDs to make other API calls on behalf of this user (using the main access_token that you normally use. You may discard this access_token after retrieving this member's information).

Step 7: Using Magic Links

Given that you have stored the refresh token from step 3 for a user, you can use the flow below to automatically log a user into the Daxko Operations Online web site. The process is as follows:

1. The user clicks a button or link within your application that will redirect the user to Operations Online (for program registration, for example).
2. Make an API call that will exchange the refresh token for an access token.
3. If this API call returns an error, then that means the refresh token is no longer valid and you must prompt the user to authenticate again and obtain a new refresh token.
4. You may now redirect the user to any Daxko Operations Online URL with the access token value appended to the query string as the parameter member_access_token. For example, if your Daxko Operations client ID is 9991, you could redirect to https://operations.daxko.com/Online/9991/ProgramsV2/Home.mvc?member_access_token=eykhbGFiOiJIUzI343I4InR4CI6IkMF