External Access & Roles

Campus One supports dynamic External Access controls, allowing developers to expand their applications beyond standard student and faculty groups to registered external (non-university) members.

This guide details how to toggle external user support in the developer portal, how the global "external" user role behaves, and how OIDC token claims are mapped during the SSO integration flow.

Enabling External Access

By default, newly registered applications are hidden from non-university users. To allow external users to discover and sign into your application:

1. Open the developer dashboard and click on your application.
2. Navigate to the Sign-In tab.
3. Scroll down to the External access card and toggle the switch to Enabled.

[ External Access Switch (Enabled) ]
Let self-registered external (non-Nile) users discover and use this app without an explicit invite.

When enabled, your application is added to the public catalog of the external users' app directory, permitting self-registration and SSO login flows.

How the "external" Role Works

The "external" role is specifically designed for users who are not affiliated with Nile University (i.e., they are not university students, staff members, or administrators). This includes guest collaborators, external program assessors, or third-party service providers who require temporary or restricted access to specific campus applications.

Unlike standard university students or faculty members, external users have restricted, opt-in access control constraints:

• Discovery: They only see and load applications in their directory if the app's External Access switch is turned ON.
• Explicit Grants: If the External Access switch is OFF, they can only access the application if an administrator explicitly grants them access via an App Access Grant (e.g. by sending them an invite link).

Token Claims & Roles Mapping

When an external user authenticates via SSO with your connected application, their global academic role and assigned custom roles are mapped into the OIDC ID Token payload.

To access these roles, ensure your application requests the roles scope during the OIDC authorization flow:

scope=openid profile email roles

OIDC Token Payload Claims

When the roles scope is granted, the following claims are returned:

1. role (String): The user's primary academic role. For all invited or self-registered non-university users, this claim is always set to:

   "role": "external"

2. roles (Array of Strings): Merges the primary academic role ("external") with any app-specific custom roles you have defined in the developer console (e.g., "tutor", "editor").

   "roles": ["external", "editor", "moderator"]

3. custom_roles (Array of Strings): Contains only your app-specific roles assigned to this user, excluding global roles.

   "custom_roles": ["editor", "moderator"]

[!NOTE] External users can also be assigned the reserved unit_admin role, which appears in roles / custom_roles and lets them manage your app's access list. See the reserved unit_admin role.

Example OIDC Decoded Token

Below is an example of a decoded OIDC token returned for an invited external user with custom app roles:

{
  "iss": "https://auth.campusone.com.ng",
  "sub": "usr_clx8z2abc123",
  "aud": "app_client_id_456",
  "exp": 1780000000,
  "name": "Kenechi Nwosu",
  "email": "kenechi.nwosu@example.com",
  "role": "external",
  "roles": [
    "external",
    "editor"
  ],
  "custom_roles": [
    "editor"
  ]
}

Connected applications can safely leverage role === "external" or inspect the custom_roles array to authorize actions or serve specialized views within their user interfaces.