CAIA OIDC Configuration

This article will walk you through setting up CAIA authentication for your WebReports environment, using OIDC (OpenID Connect).

You will need access to your WebReports configuration and a Government contact who can provide the CAIA client registration details for your environment.

1. Review the CAIA Federation Service documentation with your Government contact. Confirm which CAIA environment your WebReports application will use.

2. Obtain the following information from your Government contact:

   • Client ID
   • Client secret
   • OpenID Connect metadata URL for the intended environment
   • The registered WebReports redirect URI

   Keep the client secret in your approved secure location. Do not include it in screenshots or support messages.

3. Confirm the redirect URI with your Government contact. It must include your externally accessible WebReports URL and the callback path you will configure in WebReports.

   For example, if your WebReports URL is https://webreports.example.com and you choose /OIDCCallback as the callback path, register https://webreports.example.com/OIDCCallback. This is an example path, rather than a documented CAIA default. If your application is hosted under an additional URL path, include that path in the registered URI.

4. Open the metadata URL supplied for your CAIA environment. Copy and keep the following values for configuring WebReports:

   Metadata property	WebReports setting
   authorization_endpoint	AuthorizationEndpoint
   token_endpoint	TokenEndpoint
   userinfo_endpoint	UserInformationEndpoint

   The CAIA documentation references development metadata. Confirm the correct metadata URL with your Government contact before using it; do not assume the development URL applies to production.

5. Locate the appsettings.json file used by your running WebReports application and make a backup. For deployments that supply configuration through a managed configuration source, back up and update that source instead.
6. Open the configuration with an editor that has permission to save changes. In the existing Authentication section, set Method to CAIA.

7. Add or update the CAIA section at the same level as Authentication. The example below shows the relevant sections only. Merge these settings into your existing configuration, preserving its other settings.

   {
     "Authentication": {
       "Method": "CAIA"
     },
     "CAIA": {
       "Encrypted": false,
       "AuthorizationEndpoint": "REPLACE_WITH_AUTHORIZATION_ENDPOINT",
       "TokenEndpoint": "REPLACE_WITH_TOKEN_ENDPOINT",
       "UserInformationEndpoint": "REPLACE_WITH_USERINFO_ENDPOINT",
       "Callback": "/OIDCCallback",
       "ClientId": "REPLACE_WITH_GOV_CLIENT_ID",
       "ClientSecret": "REPLACE_WITH_GOV_CLIENT_SECRET",
       "Admin": "youradminaccount@yourdomain.com"
     }
   }
   

8. Set each property as follows:

   Property	Value
   Authentication.Method	CAIA
   AuthorizationEndpoint	The authorization_endpoint value from the correct CAIA metadata document.
   TokenEndpoint	The token_endpoint value from that document.
   UserInformationEndpoint	The userinfo_endpoint value from that document.
   Callback	The callback path agreed in step 3, including the leading /.
   ClientId	The client ID supplied by your Government contact.
   ClientSecret	The client secret supplied by your Government contact.
   Admin	The email address returned by CAIA for your intended WebReports administrator. Separate multiple addresses with a semicolon.
   Encrypted	The example uses false for values entered without WebReports configuration encryption. Preserve an existing encrypted configuration and use its established encryption procedure when making changes.

   Replace every placeholder before saving. Keep string values inside double quotes and boolean values such as false without quotes. Maintain valid JSON, including commas between properties and sections.

9. Save the configuration and restart the WebReports application using the restart procedure for your deployment. If configuration is generated or mounted during deployment, ensure your changes are retained when the application restarts or is redeployed.
10. Browse to your externally accessible WebReports URL and test CAIA sign-in. Use the intended administrator account for the initial validation. Confirm that you return to WebReports successfully and that the account has the required administrative access. Verify existing accounts’ roles in WebReports rather than assuming the configuration will change those roles.
11. Test a regular user account and confirm that its WebReports roles and report access are appropriate.

Important Troubleshooting notes:

• Use Authentication.Method: CAIA and the CAIA configuration section for these steps. 
• The client registration, credentials and endpoints must all belong to the same CAIA environment (development, test, or production).
• If sign-in reports a redirect URI mismatch, compare the registered URI with the external WebReports URL and configured callback path, including any application URL prefix.
• If authentication succeeds but WebReports access is incorrect, verify the email returned by CAIA and the account’s WebReports roles.
• If the application fails to start after the change, check the configuration format and application logs. Restore the backed-up configuration if needed.
• This procedure covers WebReports configuration. The Government supplies the CAIA registration details and any environment-specific onboarding requirements.