OpenID Connect

IGUHealth supports the following RFCs

• OAuth 2.0: https://datatracker.ietf.org/doc/html/rfc6749
  • Authorization code grant
  • Client credentials grant
• Client Registration: https://openid.net/specs/openid-connect-registration-1_0.html
• OpenID Connect Discovery: https://openid.net/specs/openid-connect-discovery-1_0.html
• Proof of Key for Code Exchange: https://datatracker.ietf.org/doc/html/rfc7636

Endpoints

To view oidc endpoints navigate to https://<api-domain>/w/<tenant>/oidc/.well-known/openid-configuration

Name	URL	Description
Discovery Document	https://<domain>/w/<tenant>/oidc/.well-known/openid-configuration	OpenID metadata information, used to automatically configure clients see https://openid.net/specs/openid-connect-discovery-1_0.html.
User Information	https://<domain>/w/<tenant>/oidc/auth/userinfo	Looks up information about a user based on access token.
Token Endpoint	https://<domain>/w/<tenant>/oidc/auth/token	Obtain a token, method will very based on Client Application grant type.
Authorization Endpoint	https://<domain>/w/<tenant>/oidc/auth/authorize	Authenticates and authorizes a user.
Logout	https://<domain>/w/<tenant>/oidc/interaction/logout	Logs a user out.

Client Registration

To register a client, you need to make a POST request to the client registration endpoint at https://<api-domain>/w/<tenant>/api/v1/fhir/r4/ClientApplication. We use a custom resource type ClientApplication to register clients using the FHIR API see here for more details.

Testing

To test the OIDC endpoints you can do the following:

1. Go to https://<tenant>.admin.iguhealth.app/ or equivalent if hosting our admin-app on your own.
2. Navigate to Client Applications by clicking on the left sidebar under security
3. Click new and fill in the following parameters:

• name: AUTH_TESTING
• grant-type: Authorization code
• redirectUrl: https://openidconnect.net/callback

4. Click actions and create
5. Make a note of the id of the newly registered client.
6. Navigate to https://openidconnect.net/
7. In discovery document url fill in https://<api-domain>/w/<your-tenant-id>/oidc/.well-known/openid-configuration
8. Click Use discovery document (token, authorization, jwks url should automatically be populated).
9. Fill in the clientID with the value from step 4.
10. Run through The debugger verifying each step (starting step is 1 Redirect to OpenID Connect Server).

Frontend React

We have react components and hooks that will setup authentication on your application. To use it do the following:

Provider

import { IGUHealthProvider, useIGUHealth } from "@iguhealth/components";

<IGUHealthProvider
  domain={REACT_APP_FHIR_BASE_URL || ""}
  tenant={"my-tenant-id"}
  clientId={"my-client-id"}
  redirectUrl={window.location.origin}
>
  <App />
</IGUHealthProvider>;

Hook

function App() {
  const iguhealth = useIGUHealth();
  const [patients, setPatients] = useState<Patient[]>([]);
  useEffect(() => {
    async function fetchPatients() {
      const patients = await iguhealth.client.search_type({}, "Patient");
      setPatients(patients.resources);
    }
    if (iguhealth.isAuthenticated) fetchPatients();
  }, [iguhealth.isAuthenticated]);

  if (!iguhealth.isAuthenticated) {
    return <div>Not authenticated</div>;
  }
  return <div>{JSON.stringify(patients)}</div>;
}