...
Google and Facebook have both an automated and manual verification and review process, according to the type of client, scope and claims the client has access to. (See https://developers.google.com/apps-script/guides/client-verification and https://support.google.com/cloud/answer/9110914?hl=en).
Verification Procedure
As of November 2019 the OAuth Clients needs to be verified in order to be usable. A dedicated OAuth Verification Job in the ops build system has been created to perform verification of a specific client. The following procedure can be used in order to verify a client:
Once a request is received and the client needs to be verified, create a new ticket in JIRA with the client id
Launch the OAuth Verification Job filling out the required parameters (Note: you will need a Jenkins account):
SESSION_TOKEN: A valid session token for an admin user
CLIENT_ID: the id of the client to verify
ETAG: The etag of the client to verify (this is to ensure that the client didn’t change after the client details were read)
VERIFY_STATUS: Leave enabled (deselecting would un-verify a client)
Resolve the related JIRA issue
Initial Implementation
As from the design review meeting held on the 11th of November 2019 the synapse team decided that due to the number of expected use cases a complete verification process is not needed and the initial implementation will be based on white listing on a case by case the oauth clients:
Client will not be usable after creation until verified. If a client is being (e.g. to get an authorization code or access token) used while not verified an error message should include a the email to contact in order to verify the client.
In the Web Client a form to submit a Jira issue to the ACT team to request the client verification will be shown (as part of
)Jira Legacy server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key SWC-4957 A user should be blocked in the web client from using a non verified client (
)Jira Legacy server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key SWC-5043 An administrative API (Only ACT and admins can invoke this endpoint) will be added to verify a client:
Code Block PUT /admin/oauth2/client/{id}/verified?status=<boolean>
The initial proposed design below is still valid and can be taken into account in the future when/if the verification will be extended.
Proposed Approach for Synapse
...
In case of rejection a reason must be included explaining why. A user should be able to update the client and perform another submission after being rejected.
Domain validation
In addition to the manual approval or rejection, we should establish ownership of the domain referred to by the redirect uri (s) in the client as an additional trust layer. Note that while the specification does not enforce the scheme for redirect uris for web application types (See application_type in https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata), it allows custom schemes for "native" applications. Since we do not support native applications and the specification does not explicitly forbid it, we can enforce the redirect uri scheme to be https. In this way we can assume that we should always be able to verify the domain ownership.
...
If the sector_identifier_uri is provided during the client registration the list of redirect uris might potentially contain multiple domains. In order for a client to be validated all of the URIs needs to pass the domain validation.
Verification Status
A verification submission is associated with a status, one of: SUBMITTED, REJECTED, APPROVED. A verification approval is tied to the domain validation, the verification will include the information about the domain validation status. The verification cannot be approved if the domain is not validated.
...
We should allow to bypass the verification submission (e.g. for internal use or other mean of verification), in this case a submission from the user is not necessary and the client can be verified with a dedicated API call.
Proposed API
DT = Designated team for the verification review.
METHOD | URI | Notification | Request | Response | Description |
|---|---|---|---|---|---|
POST | /oauth2/client/{id}/verification | To the DT to review the verification request | OAuthClientVerification | OAuthClientVerification | Allows the user to submit a new verification for the client. Only the creator of the client can make this call. |
GET | /oauth2/client/{id}/verification | OAuthClientVerification | Gets the current verification for the client if any. Only the creator of the client can make this call. | ||
GET | /oauth2/client/{id}/verification/validationCode | OAuthClientValidationCode | Allows the user to retrieve the validation code used for domain validation. The code is generated once when the verification is submitted. | ||
POST | POST /oauth2/client/{id}/verification/status | To the verification creator | OAuthClientVerificationStatus | OAuthClientVerificationStatus | Allows the DT to approve/reject the verification. The possible state transitions are: SUBMITTED → APPROVED SUBMITTED → REJECTED |
POSTPUT | /admin/oauth2/client/{id}/verified?status=<boolean> | Allows the DT to bypass the verification and set the client as verified or not independently from the verification. | |||
GET | /oauth2/client/verification | OAuthClientVerificationList | Allows the DT to retrieve a paginated list of verifications (sorted by creation date desc), optional parameters:
|
...
Field | Type | Description |
|---|---|---|
cliendId | long | The id of the client |
code | string | The code for the domain validation for any of the registred redirect uris |
User Interaction
There are three main actors involved in the verification
...
For C, the user should be informed if the client is not verified and the consent should be discouraged.
References
...
https://tools.ietf.org/html/rfc6749
https://tools.ietf.org/html/rfc8252
...