Dartmouth API Developer Portal

Banner Impersonation API

Allows developers and testers in non-production environments to impersonate other peoples accounts. This API works specifically in setting Banner up for impersonation. There are three calls used in this API, a PATCH request to initiate impersonation, a GET request to inquire about the current status of impersonation and a DELETE request to end an impersonation session.

Calling this API in a production environment will return an error.

Required Scopes

Scope	Description
"urn:dartmouth:banner_impersonation:write.sensitive"	This scope is required on all requests to this API

When a request is made against the endpoint without the required scope, a 403 return code is given and the following error payload:

{
  "status": "FAILURE",
  "message": "Required scope missing."
}

Initiate Impersonation Request

PATCH /api/banner_imp/{netid}

Required Headers

Authorization: Bearer {jwt}

Sample Patch Body Payload

{
    "as_netid":"f00245x"
}

Attribute Descriptions

Field	Type	Sample Data	Description	Known Issues
as_netid	string		the netid of the identity being impersonated

Notes on usage

The PATCH call initiates Banner impersonationation for the tester identified by the {netid} in the call. The payload contains the netid the impersonator is trying to impersonate.

Impersonation is authorized and set up by the Student Team. A user with the correct scope but has not been authorized to impersonate will receive the following error

{
  "status": "FAILURE",
  "message": "SQL Error",
  "details": "java.sql.SQLException: ORA-20001: Not authorized to impersonate.\nORA-06512: at \"BAN_DATA_MGR.DC_B9_IMPERSONATE\", line 303\nORA-06512: at \"BAN_DATA_MGR.DC_B9_IMPERSONATE\", line 332\nORA-06512: at \"DART_IPAAS.IPAAS_BANNER_IMP\", line 18\n"
}

Only one impersonation can be in effect at any point in time. Attempting to impersonate another person while impersonation is already in effect results in a 400 return code and the following error payload:

{
  "status": "FAILURE",
  "message": "SQL Error",
  "details": "java.sql.SQLException: ORA-20001: Impersonation in progress for student\nORA-06512: at \"BAN_DATA_MGR.DC_B9_IMPERSONATE\", line 303\nORA-06512: at \"BAN_DATA_MGR.DC_B9_IMPERSONATE\", line 332\nORA-06512: at \"DART_IPAAS.IPAAS_BANNER_IMP\", line 18\n"
}

Get Impersonation Status

GET /api/banner_imp/{netid}

Sample Return Get Body Payload

{
    "as_netid":"f00245x"
}

End Impersonation Status

DELETE /api/banner_imp/{netid}