Autentificare¶
QFieldCloud and QField / QFieldSync clients allow authentication using regular username and password, or, if configured, OpenID Connect with a third-party identity provider.
OpenID Connect authentication¶
OpenID Connect (OIDC) is an industry standard authentication protocol on top of OAuth2 that allows to delegate authentication to an identity provider (IDP) such as Google, Microsoft, or any other OpenID Connect compliant provider. This allows users to log in to QFieldCloud using their existing accounts with these providers, without needing to create a separate account for QFieldCloud.
OIDC can be used directly for signing up with QFieldCloud, or for signing in to an existing QFieldCloud account (matched via verified email address).
QFieldCloud (Web)¶
Here is a sequence diagram of how a third-party login happens in QFieldCloud (in the browser):
sequenceDiagram
autonumber
actor User as User (Browser)
participant QFC as QFieldCloud
User ->> QFC: Access login page
QFC -->> User: Display login form with configured third-party login buttons
User ->> QFC: Click third-party login button
QFC -->> User: Redirect to IDP for login
create participant IDP as Identity Provider
User ->> IDP: Follow redirect to IDP login page
IDP -->> User: Display IDP's login page
User ->> IDP: Authenticate using IDP credentials
IDP -->> User: Redirect to QFieldCloud callback URL with authorization code
User ->>+ QFC: Hand authorization code to QFieldCloud
QFC ->> IDP: Exchange authorization code for access token and ID token
IDP -->> QFC: Return access token + ID token
Note over QFC: Validate ID token signature
QFC ->> IDP: Request user profile information
destroy IDP
IDP -->> QFC: Return user profile information
alt If user does not already have a QFieldCloud account
note over QFC: QFieldCloud account is created using IDP profile infos
end
QFC -->>- User: Log user in (establish session)
QField / QFieldSync¶
Here is a sequence diagram of how third-party authentication happens in QField and QFieldSync:
sequenceDiagram
autonumber
participant IDP as Identity Provider
actor User
participant QF as QField / QFieldSync
participant QFC as QFieldCloud
User ->>+ QF: Open the QFieldCloud login dialog
QF ->> QFC: Ask for list of identity providers
QFC -->> QF: Answer with list of identity providers
QF -->>- User: Display a button for each identity provider
User ->>+ QF: Click on 'Login with XYZ' provider button
QF ->> IDP: Redirect to IDP for login
IDP -->> User: Display IDP's login form in a browser
User ->> IDP: Log in using IDP's credentials in the browser
IDP -->> QF: Answer with authorization code
QF ->> IDP: Exchange authorization code for access token and ID token
IDP -->> QF: Answer with access token and ID token
QF ->> QFC: Use ID token to authenticate user
Note over QFC: Validate ID token signature
QFC -->> QF: Establish user session and return user info
QF -->>- User: User is logged in and authenticated
loop HTTP requests to QFieldCloud
QF ->> QFC: Send a request (e.g. file Download/Upload)
Note over QF,QFC: Tokens are attached to requests in HTTP headers
QFC -->> QF: Reply to the request
end
loop refresh token regularly
QF ->> IDP: Ask for a new token
IDP -->> QF: Send a refreshed token
end
Details¶
-
Open the QFieldCloud login dialog User clicks on the QFieldCloud login button in QField / QFieldSync
-
Ask for list of identity providers Query the QFieldCloud
api/v1/auth/providers
endpoint for a list of enabled identity providers, and their configuration details. -
Answer with list of identity providers Return the list of enabled identity providers. For each IDP this will include information to render the UI (title, logo, colors), and also the necessary OIDC configuration details for the given IDP. These include properties like the client ID, token URL, etc. for QField/QFieldSync to connect to the IDP.
-
Display a button for each identity provider For each enabled authentication method a login button is rendered.
-
Click on 'Login with XYZ' provider button User clicks the button to log in with a particular provider. At this point, QField/QFieldSync will create a new
QgsAuthMethodConfig
of type OAuth2, and will use the OIDC configuration details received from QFieldCloud to configure it. -
Redirect to IDP for login QField/QFieldSync will then open a browser window and send the user to the IDPs login page. In the URL for that login page a redirect_url is included which points back to the callback at which QField/QFieldSync will receive the IDP's response that will include the authorization code. For that purpose, QField/QFieldSync will spawn a temporary web server at
http://localhost:7070
which will receive that callback. -
Display IDP's login form in a browser The IDP presents the user with a login page and a consent form.
-
Log in using IDP's credentials in the browser The user authenticates to the IDP, using whichever authentication method the IDP supports (username/password, client certificate, session, ...).
-
Answer with authorization code The IDP will redirect the user's browser back to the redirect_url, where QField/QFieldSync's temporary webserver will receive the callback, which includes the long lived OIDC authorization code.
-
Exchange authorization code for access token and ID token QField/QFieldSync will send the authorization code to the IDP's token endpoint, and exchange it for ID token, access token and refresh token.
-
Answer with access token and ID token The IDP verifies the authoritation code (with the addition of PKCE), and responds with ID token, access token and refresh token, which are short lived.
-
Use ID token to authenticate user QField/QFieldSync will send the ID token and access token to QFieldCloud, and request the user's profile information.
-
Establish user session and return user info QFieldCloud will verify the ID token's signature and authenticate the user. If successful, it responds with the user's profile information and a user session.
-
User is logged in and authenticated QField/QFieldSync will receive and store the user's profile information and authentication session.
Request loop¶
-
Send a request (e.g. file Download/Upload) Once a user has authenticated with the IDP, and QField/QFieldSync has received the OIDC tokens, it will attach the ID token and access token in subsequent requests to QFieldCloud as HTTP request headers. (Technically speaking, it's actually the QGIS auth manager which will do this). The access token is included as an
Authorization: Bearer <access_token>
HTTP header, and the ID token is included in theX-QFC-ID-Token
HTTP header. The IDP provider type (e.g.google
) is included in theX-QFC-IDP-ID
HTTP header, to let QFieldCloud know which IDP the token needs to be verified with. -
Reply to the request QFieldCloud will authenticate the user, either through an existing session, or through the OIDC tokens, and respond to the request.
Token refresh loop¶
-
Ask for a new token QField/QFieldSync will regularly refresh the ID and access tokens by calling the IDP's token refresh endpoint and submitting the refresh token it received.
-
Send a refreshed token The IDP will respond with new ID and access tokens.