Rapid Connect Integration
Integration
Before you get started with AAF Rapid Connect, you MUST meet all the following high level requirements:
- You must be using HTTPS on your webserver for all JWT related endpoints. You should be using HTTPS for your entire application.
- The organisation which owns the service you’re registering must be an existing AAF subscriber.
- You must have an existing account with an AAF connected Identity Provider which you use to access AAF services.
1. Select a JWT library
To get started with AAF Rapid Connect integration, select a suitable JWT library from the following table for your application. These libraries will assist developers in quickly implementing JWT support. Libraries are not listed in any particular order and not endorsed by us. You should evaluate them individually to determine which best suits your needs. Found a useful JWT library not listed here? Please let us know about it.
| Language | Library | Contributor |
|---|---|---|
| Ruby | Devise and OmniAuth | James Barona from the South Australian Health and Medical Research Institute |
| Specific integration example in gist | ||
| progrium ruby-jwt | ||
| Java | nimbus-jose-jwt | |
| Google Code Archive jsontoken | ||
| Oracle jwt | ||
| Python | magical jwt-python | |
| progrium pyjwt | ||
| Example authenticator for CKAN | Louis Des Landes at Swinburne University of Technology | |
| PHP | cfrett JWT-PHP | |
| luciferous jwt | ||
| Node | hokaccha node-jwt-simple | |
| .Net | johnsheehan jwt | |
| NuGet JWT | ||
| Go | mendsley gojwt | |
| Perl | Example Perl Code | Michael Lynch from EResearch Support Group, Information Technology Division, University of Technology, Sydney |
| Haskell | Hackage jwt | |
| rapid-connect-yesod-demo | Dr Carlo Hamalainen, Centre for Advanced Imaging, University of Queensland | |
| Dart | aaf_rapid_connect |
2. Create a secret
The first step in integrating your code is to compute a secret that will be shared between your application and AAF Rapid Connect for signing and verifying JWT.
Recommended secret generation method on *nix hosts, 32 characters long:
| LC_CTYPE=C tr -dc '[[:alnum:][:punct:]]' < /dev/urandom | head -c32 ;echo
This value should never be publicly disclosed. Once created be sure to store it securely. This value will be required during service registration.
3. Provide a web accessible endpoint
Your application MUST define a https endpoint which accepts a HTTP POST request. The endpoint must acquire the data provided in the parameter assertion for further processing.
4. Validate the signed JWT (JWS) your application has received
Should any stage of the below validation fail your application MUST discard the token and present the user with a suitable error message.
- Verify that the signature for the signed JWT you have received is valid by using your locally stored secret value
- Ensure that the iss claim has the value https://rapid.aaf.edu.au when in the production environment, or https://rapid.test.aaf.edu.au when in the test environment.
- Ensure that the aud claim has the value of your application’s primary URL (provided as part of service registration).
- The current time MUST be after or equal to the time provided in the nbf claim.
- The current time MUST be before the time provided in the exp claim.
- Ensure that the value of the jti claim does not exist in a local storage mechanism of jti claim values you have accepted. If it doesn’t (this MUST be the case) add the jti claim value to your local storage mechanism for protection against replay attacks.
All applications connecting to the AAF must adhere to all relevant AAF rules and policies. Prior to approving the connection of your service to the federation, the AAF may request to review your JWT related code and test your running endpoint to verify that an application’s JWT handling conforms to the above requirements.
5. Make use of the user’s personal information
Your application now has a fully verified JWT provided by AAF Rapid Connect.
By looking at the claim https://aaf.edu.au/attributes you will be able to access information about the user which most Research and Scholarly applications require. The following core AAF attributes should be available:
1. cn
2. mail
3. displayname
4. edupersontargetedid
5. edupersonscopedaffiliation
6. organizationname
The following optional AAF attributes MAY be available at the discretion of the user’s Identity Provider:
1. edupersonprincipalname: The "NetID" of the person for the purposes of inter-institutional authentication.
2. givenname: A person's first name or preferred name
3. surname: A person's surname
4. edupersonorcid: A person's ORCID (https://orcid.org/) identifier, if they have provided one.
You may also be provided with the auedupersonsharedtoken attribute if your use case requires it. For more information on auedupersonsharedtoken, see this support article.
You can now use this data to create a local account suitable for internal use by your application, for customisation and other purposes. It is RECOMMENDED that you use the data provided in either the JWT claim sub or the https://aaf.edu.au/attributes claim’s edupersontargetedid field to uniquely identify users.
The JWT claim sub and the https://aaf.edu.au/attributes claim’s edupersontargetedid field are always identical for Rapid Connect. The same value SHALL be provided for all subsequent visits to your application by each user. The full value of the field MUST be utilised to ensure your application uniquely identifies the remote user. Applications MUST NOT split this value based on the delimited bang segments.
The value of sub/edupersontargetedid is not able to correlate a user between services. For more details see http://wiki.aaf.edu.au/tech-info/attributes/edupersontargetedid.