Page Comparison

Table of Contents
maxLevel 2

With the implementation of https://sagebionetworks.jira.com/browse/

Jira Legacy
server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key PLFM-4585

synapse can now act as an OAuth 2.0 Provider. In order for application clients (See roles in https://tools.ietf.org/html/rfc6749#section-1.1) to use Synapse as a resource server our implementation of the authorization server requires the client application to be registered before issuing authorization codes and access tokens.

Once a client is registered it can perform scoped operations on behalf of the user, at the time of writing we support the openid scope for the Open ID Connect /userInfo service. In the future we will extend the scope (and claims) that would allow access to data that with the user consent.

One of the issues in the OAuth architecture is that while authentication and authorization is decoupled from a client application in a secure manner, establishing trust on the client application is not defined by the specification.

Since that the data that synapse users can access might potentially be sensitive according to the scopes and claims, we need a way to establish trust with a client application by having a process in place to verify that the application will not misuse and/or abuse the system. There is not a standard (automated or manual) procedure for verifying a client in the industry and different companies take different approaches (or choose not to have a verification process).

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).

Proposed Approach for Synapse

...

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:

1. Once a request is received and the client needs to be verified, create a new ticket in JIRA with the client id

2. Launch the OAuth Verification Job filling out the required parameters (Note: you will need a Jenkins account):

   1. SESSION_TOKEN: A valid session token for an admin user

   2. CLIENT_ID: the id of the client to verify

   3. ETAG: The etag of the client to verify (this is to ensure that the client didn’t change after the client details were read)

   4. VERIFY_STATUS: Leave enabled (deselecting would un-verify a client)

3. 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:

1. 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.

2. 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

   )

3. 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

   )

4. 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

We propose to introduce a (manual) verification step for application clients that are registered in synapse which is similar to the user verification (https://sagebionetworks.jira.com/wiki/spaces/PLFM/pages/82935813/Verified+User). The manual verification will be implemented on top of an automatic validation of ownership of the domain in the redirect uri(s) submitted by the client. We allow registration and usage without verification but the web client should show a banner if a user consenting to an application that has not been verified. The banner should clearly state that the application is not verified and discourage the user to consent.

...

1. The client, policy and tos uris should be filled out

2. The client, policy and tos uris domain should match that at least one of the domains in the list of redirect uris (As suggested in https://openid.net/specs/openid-connect-registration-1_0.html#Impersonation). This should be validated at registration time.

3. The redirect uris scheme should be https and the host should not be localhost or loopback (127.0.0.1, ::1)

4. The client should have generated a secret

5. .1, ::1). Note that a client can still be registered with a localhost or loopback for testing, but verification would not be available.

6. A natural language description of the application must be included in the submission

...

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.

...

The validation code is verified by the backend asynchronously, a worker will try and verify all the clients that are still pending. We might want to implement multiple retries before automatically rejecting a verification submission because of a failed domain validation (e.g. code mismatch).

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.

If the verification is reject rejected the user should resubmit the verification with any changes indicated in the rejection reason.

Once the verification is approved the client verified property is set. Any change to the client metadata that is required for verification leads to the client verified property to be reset and a new verification should be submitted by the user. Similarly to the user verification we maintain a list of status changes with the user who changed the status. Multiple verification submissions might be present for a single client. The domain validation is tied to the verification submission.

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.

API Changes

There are some API changes needed in order to support this workflow, in particular a client is not usable if a secret was not generated and we therefore required the presence of a secret for verification. Our implementation deviates somehow from the specification, in the sense that the secret is not generated at registration time and is not returned in the GET /oauth2/client response. Instead we have a dedicated POST /oauth2/client/secret/{id} (shouldn't this be the user verification we maintain a list of status changes with the user who changed the status. Multiple verification submissions might be present for a single client. The domain validation is tied to the verification submission.

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.

...

For the web client to show the requirements for verification it needs to be able to gather the current status of the secret, we propose to include a boolean property secret_generated in the response of the GET /oauth/client/{id} which would also allow the web client to inform the user that a secret needs to be generated.

Additionally we might want to add a new API call that returns the current secret for the user

GET /oauth2/client/secret/{id}

Proposed API

DT = Designated team for the verification review.

...

API Models:

API Models

OAuthClientVerificationStatus

OAuthClientDomainValidationStatus

OAuthClientVerification

...

OAuthClientVerificationList

OAuthClientValidationCode

OAuthClientVerification

OAuthClientVerificationList

...

User Interaction

There are three main actors involved in the verification

A. The user that registered a client and needs to submit the verification.

B. The user that reviews the submission

C. The end user using the client

For A (tracked in

Jira Legacy
server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key SWC-4957

) the user should be able to:

1. See that the client is not verified with information about the consequences

2. Submit a verification if not verified already

3. Get the domain validation code, with instructions on how to use it. Potentially a file download with the validation code to be placed as is on a web server.

4. Check the status of the verification, including the domain validation status.

For B the user should be able to:

1. See the list of submitted verifications

2. Review the information of the client, including the description submitted with the verification, the client, tos and policy uris and a link to the user profile.

3. Check the domain validation status for the client, if the domain is not validated yet approval is not allowed.

4. Approve or reject the verification, allowing to input a reason

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

...