OAuth2 Capabilities¶

Touchstone has the ability for a user to create and use a Test System that is OAuth2 enabled, and with that comes of few features that are important to take note of when it comes to Test Executions performed against a Test System that has an OAuth2 Authorization service connected to it.

Fixture ID’s¶

With the addition of a more robust OAuth2 environment into Touchstone, there are a few fixtures, and values under those fixtures, that can be reached for test script authors.

One fixture is the dest1SmartConfig (dest2SmartConfig, dest3SmartConfig, etc.). The fixture allows the test script author to access different variables coming from the JSON document that is at the .well-known/smart-configuration.json endpoint. It acts the same as retrieving variables from the capabilities statement. For example, to use dest1SmartConfig to retrieve the Client ID, you would use the sourceId and path in the testscript as sourceId = dest1SmartConfig, path = $.clientId.
Test Systems have special Oauth2 values that can be be retrieved by test script authors. The fixtures have a naming convention of dest1SystemConfig, dest2SystemConfig, origin1SystemConfig, origin2SystemConfig, etc. These fixtures have the following attributes:

Fixture ID	Description
name	The Test System name
fullName	The Organization name + the Test System name
baseUrl	The Base URL of the Test System
supportsSmartOnFhir	Set to `true` if the Test System supports SMART on FHIR, `false` if it does not
oauth2GrantType	The Grant Type of the OAuth2 enables Test System, either Authorization Code or Client Credentials
clientId	The Client ID of the Test System that is registered with the OAuth2 server.
clientSecret	The Client Secret of the Test System that is registered with the OAuth2 server.
authEndpoint	The Authorization Endpoint for the Test System.
tokenEndpoint	The Token Endpoint for the Test System.
registerEndpoint	The Registration Endpoint for the Test System.
introspectEndpoint	The Introspection Endpoint for the Test System.
revocationEndpoint	The Revocation Endpoint for the Test System.
scopesSupported	The scopes that allowed for the server access to certain user scopes

An example of using these fixtures in a test script is below:

Another set of fixtures that can be used by the user in the test scripts are oauth2AuthzRequest and oauth2AuthzRedirect. These two fixtures are used to access parts the the last OAuth2 Authroization Request sent to the OAuth2 server and the last OAuth2 Authorization response returned from the server.

Base64Encoding¶

Touchstone is configured to use a Base64Encoding on the operation.requestHeader.value when it includes Basic + A Single Space " " ahead of the value and when the operation.requestHeader.name is equal to Authorization in your Testscript executions. This is done for security and is the explanation as to why an Authorization value in the header will be different from the one that was originally coded.

PKCE Functionality¶

Executing SMART testcases using PKCE needs Code Verifier (which is a randomly generated string meeting a certain requirement) and a Code Challenge (which is a string generated by hashing the Code Verifier and a Code Challenge Method).
The groovy rule PKCECodeExchange.groovy under FHIRCommon can be used for generating the Code Verifier, Code Challenge and the Code Challenge Method.

Steps to include PKCE information in a SMART Testcase,

Define an extension to include the rule PKCECodeExchange.groovy

Example:

<extension url="http://touchstone.aegis.net/touchstone/fhir/testing/StructureDefinition/testscript-rule">
        <extension url="ruleId">
                <valueId value="rule-fetchCodeExchange" />
        </extension>
        <extension url="path">
                <valueString value="/FHIRCommon/_reference/rule/PKCECodeExchange.groovy" />
        </extension>
</extension>

Create an assertion and place it before any operation that requests the authorization code

Example:

<action>
        <assert>
                <extension url="http://touchstone.aegis.net/touchstone/fhir/testing/StructureDefinition/testscript-assert-rule">
                        <extension url="ruleId">
                                <valueId value="rule-fetchCodeExchange" />
                        </extension>
                        <extension url="output">
                                <extension url="name">
                                        <valueString value="codeChallenge" />
                                </extension>
                        </extension>
                        <extension url="output">
                                <extension url="name">
                                        <valueString value="codeChallengeMethod" />
                                </extension>
                        </extension>
                        <extension url="output">
                                <extension url="name">
                                        <valueString value="codeVerifier" />
                                </extension>
                        </extension>
                </extension>
                <extension url="http://touchstone.aegis.net/touchstone/fhir/testing/StructureDefinition/testscript-assert-stopTestOnFail">
                <valueBoolean value="true" />
                </extension>
                <description value="Generates CodeChallenge and CodeVerifier." />
                <warningOnly value="false" />
        </assert>
</action>

Include the Code Challenge and Code Challenge Method to the URL under the Authorization Request Operation

Example:

<action>
        <operation>
                <extension url="http://touchstone.aegis.net/touchstone/fhir/testing/StructureDefinition/testscript-operation-oauth2AuthzRequestId">
                        <valueId value="oauth2AuthzRequest1" />
                </extension>
                <extension url="http://touchstone.aegis.net/touchstone/fhir/testing/StructureDefinition/testscript-operation-oauth2AuthzRedirectId">
                        <valueId value="oauth2AuthzRedirect1" />
                </extension>
                <type>
                        <system value="http://touchstone.aegis.net/touchstone/fhir/testing/CodeSystem/codesystem-testscript-operation-codes" />
                        <code value="oauth2-authorize" />
                </type>
                <description value="Redirect user to the authorize endpoint for target test system specified in smart configuration" />
                <encodeRequestUrl value="true" />
                <url value="${authorizeEndpoint}?client_id=${dest1SystemConfig.clientId}&amp;scope=${oauth2RequiredScopes}&amp;aud=${dest1SystemConfig.baseUrl}&amp;code_challenge=${codeChallenge}&amp;code_challenge_method=${codeChallengeMethod}" />
        </operation>
</action>

Add the Code Verifier to the Access Token Request. Note: If a Fixture is used for loading the token request parameters, update the fixture with this parameter

Example:

grant_type=authorization_code&code=${oauth2AuthzRedirect1AuthCode}&redirect_uri=${oauth2AuthzRequest1RedirectUri}&code_verifier=${codeVerifier}