Integration Guide¶

To embed a Sharecare Prebuilt Component into your web or mobile experience

1. Obtain an API Key through Customer Onboarding
2. Create a Sharecare account via account registration
   1. This must be performed prior to Single Sign-On
3. Establish a User Session
4. Deep link into the desired feature
   1. Examples: RealAge test or results screens

Client Applications

1. Deep link to the feature or present a call to action
2. Launch a web view with a client authenticated user session
3. Invoke the Single Sign-On process with Sharecare as the service provider and the client identity platform as the IDP
4. Present the feature to the user

Integration Steps¶

Choose one of the following approaches for App 2 App integration.

1. OAuth 2.0 Authorization code flow (response mode is query) OR
2. OAuth 2.0 implicit grant flow with response mode of either form post or fragment

Implementation Activities for OAuth 2.0 based Integration¶

1. Client’s OIDC provider must support one of the OAuth 2.0 flows mentioned earlier in this document.
2. Determine the claim name in Identity token or User Info API that is used to identify Sharecare user.
3. Register Sharecare with client OIDC provider and get the Sharecare Client ID and Client Secret from them.
4. Collect Client’s OIDC provider information.
5. Sharecare system configuration: create a Sharecare provider configuration for this integration and store it’s id in EntityID. The same configuration is used for both client’s website and App-2-App integration. Provide EntityID value to client.
6. Select the landing page inside the Sharecare application. This value is passed in relayState parameter. If no relayState is passed, the user is landed on a default page.
7. Construct the deep link as: https://auth.sharecare.com/saml2/oauth2/partner/redirect?entityId={EntityID}&relayState={relayState}. If no relayState is passed, the user is landed on a default page.
8. Add the Sharecare link in Client’s application. When user taps this link, Client app must launch the system browser, put the user session cookie and load the Sharecare link URL

Register Sharecare with client’s OIDC provider (OP)¶

For implicit flow, register the following metadata values with Client’s OIDC provider:

For Authorization code flow, register the following metadata values with Client’s OIDC provider:

Get the sharecareClientId that was created for Sharecare from the client.

Collect Client’s OIDC provider information for configuring Sharecare service.¶

Create Sharecare provider configuration for client’s OAuth 2.0 integration.¶

Create a SAML provider configuration, EntityId, for OAuth 2.0 integration using the client’s OIDC provider information we collected.

Authorization Request sent to Client’s OP authorization endpoint and expected Response¶

GET {authorizationEndpoint} 
  ?response_type=id_token
  &response_mode=form_post
  &client_id={sharecareClientId}
  &redirect_uri={redirectUri}
  &scope=openid
  &state={EntityId}
  &nonce=NONCE
  &prompt=none

POST https://auth.sharecare.com/saml2/oauth2/partner/login
  ?state=EntityId
  &id_token=XXXXX_JWT_WITH_NONCE
  &expires_in=3599

https://auth.sharecare.com/saml2/oauth2/partner/login
  ?error=user_authentication_required
  &error_description=request+could+not+be+completed+siltently

On successful Authorization response, we validate the identity token and then attempt to log that user in by performing a lookup with the member unique identifier that is specified in the ID token’s claim {claimPersistentId}. If a match is found, the application logs the user in. Should no matching record be found, the application will redirect the user to an error page.

GET https://Partner_DOMAIN/authorize
  ?response_type=code
  &client_id={sharecareClientId}
  &redirect_uri=https://auth.sharecare.com/saml2/oauth2/partner/login
    ?grant_type=code
    &redirectUri=https://feature.sharecare.com/realage/results?assessmentId=1004385&partnerId={partner-id}
  &scope=openid email
  &state={EntityId}
  &nonce=NONCE
  &prompt=none

POST https://auth.sharecare.com/saml2/oauth2/partner/login
  ?grant_type=code/{id_token:default}
  &redirectUri=https://feature.sharecare.com/realage/results?assessmentId=1004385&partnerId={partner-id}
  &state=EntityId
  &code=auyasdfasdfas.asdfasdfas.asdfasdfas
  &expires_in=3599
  --header Cookie: name=PartnerAuthNonce, value={nonce}

https://auth.sharecare.com/saml2/oauth2/partner/login 
  ?error=user_authentication_required
  &error_description=request+could+not+be+completed+siltently

User Session¶

Establishing a user session is straightforward.

The API call below initiates a redirect to the configured authentication provider for the purposes of obtaining an access grant. If successful the flows will generate a user session, and redirect to the 'relayState' URL.

https://auth.uat.sharecare.com/saml2/oauth2/partner/redirect
  ?relayState={feature-screen-URL}
  &entityId={entity-id}

https://auth.uat.sharecare.com/saml2/oauth2/partner/redirect
    ?relayState=https%3A%2F%2Ffeature.uat.sharecare.com%2Frealage%2Ftest%3FassessmentId%3D1004385%26partnerId%3D{partner-id}%26onCompleteRedirect%3Dhttps%3A%2F%2Fexample.redirect.com
    &entityId=https://generacommunity.uat.sharecare.com

Sequence Diagram: Create Session and Redirect to Feature Screen¶

In this example, we redirect to the RealAge test located here https://feature.uat.sharecare.com/realage/test?assessmentId=1004385&partnerId={partner-id}&onCompleteRedirect={redirect-uri}

sequenceDiagram
    Note right of Partner: Pass<br>https://auth.uat.sharecare.com/saml2/oauth2/partner/redirect<br>?entityId=https://partner.com<br>&relayState=https://feature.uat.sharecare.com/realage/test?assessmentId=1004385&partnerId={partner-id}&onCompleteRedirect={redirect-uri}
    Partner->>Webview: Insert Partner auth cookie

    Note left of Sharecare SSO: Call<br>https://auth.uat.sharecare.com/saml2/oauth2/partner/redirect<br>?entityId=https://partner.com<br>&relayState=https://feature.uat.sharecare.com/realage/test?assessmentId=1004385&partnerId={partner-id}&onCompleteRedirect={redirect-uri}
    Webview->>Sharecare SSO: Call Partner redirect endpoint

    Note left of Sharecare SSO: GET https://Partner_DOMAIN/authorize<br>?response_type=code<br>&response_mode=form_post<br>&client_id=Sharecare_client_id<br>&redirect_uri=https://auth.uat.sharecare.com/saml2/oauth2/partner/login<br>&scope=openid<br>&state=https://partner.com<br>&nonce=NONCE<br>&prompt=none
    Sharecare SSO->>Webview: Authorize user
    Webview->>Partner: Authorize user

    Note right of Partner: Header<br>Location: https://auth.uat.sharecare.com/saml2/oauth2/partner/login<br>?state=https//partner.com<br>&code=XXXXX
    Partner->>Webview: Return authorization code
    Webview->>Sharecare SSO: Return authorization code

    Note left of Sharecare SSO: POST<br>https://partner.com/token?grant_type=code
    Sharecare SSO->>Partner: Exchange Code for token
    Partner->>Sharecare SSO: Return id_token or access_token

    alt id_token
        Sharecare SSO->>Sharecare SSO: Find ClaimId
    else access_token
        Sharecare SSO->>Partner: Fetch user info
        Partner->>Sharecare SSO: Return user info
        Sharecare SSO->>Sharecare SSO: Find ClaimId in user response
    end

    Sharecare SSO->>Sharecare SSO: Create SSO session in browser

    Note left of Sharecare SSO: Header<br>Location: https://feature.uat.sharecare.com/realage/test?assessmentId=1004385&partnerId={partner-id}&onCompleteRedirect={redirect-uri}
    Sharecare SSO->>Webview: Redirect user to realage

    Note over Webview: Bounce the user to realage<br>using page.js#authorize
    Webview->>Realage: Realage get the Sharecare auth code
    Realage->>Sharecare SSO: Exchange code for access_token
    Sharecare SSO->>Realage: Receive access token
    Realage->>Webview: Create Realage application cookie

Steps to Integration¶

• Begin in the Stage environment to familiarize yourself with and develop against Sharecare APIs.
• Perform a comprehensive regression test of the partner's onboarding and access flows in the Stage environment to validate that the APIs are being used as expected.
• Once testing in the Stage environment is complete, promote the application to the UAT (User Acceptance Testing) environment.
• Conduct a smoke test in the UAT environment by executing the onboarding and access flows to ensure they function correctly.
• If necessary, involve the client in validating the configuration of the application.
• Upon successful testing in the UAT environment, proceed to promote the application to the Production environment.
• Perform a smoke test in the Production environment by executing the onboarding and access flows to verify their proper functioning in the live environment.