Sign people in

Read who is signed in

datumhue.identity.is_signed_in tells any app whether someone is signed in. Who it is takes the identity permission: identity.sub, identity.email, identity.name, identity.issuer and identity.claims read the signed-in account, or nil while nobody is signed in. A package asks for the permission in its manifest, with capabilities "identity"; a script you run with datumhue run holds it already (Permissions and capabilities).

identity.sub is the provider's id for the account. It stays the same when the person changes their name or email. identity.email is the address as the provider sent it, which may be unverified: the provider vouches for it only when identity.claims().email_verified is true, so tell accounts apart by identity.issuer and identity.sub together.

Sign in and hear the outcome

identity.sign_in starts a sign-in with the provider your deployment configured under the issuer name you pass. The sign-in page opens in the browser, and the outcome arrives later, as events every app hears:

local identity = datumhue.identity
local events = datumhue.events

local status = datumhue.ui.root:label({ text = "Signed out" })

events.on("identity_signed_in", function()
    status.text = "Signed in as "
        .. (identity.name() or identity.email() or identity.sub())
end)
events.on("identity_sign_in_failed", function(e)
    if e.error_kind ~= "cancelled" then
        status.text = "Couldn't sign in. " .. e.error_message
    end
end)
events.on("identity_signed_out", function()
    status.text = "Signed out"
end)

if identity.is_signed_in() then
    status.text = "Signed in as " .. identity.sub()
else
    identity.sign_in({ issuer = "datumhue" })
end

• identity_signed_in says someone signed in, and carries nothing: read who it is through datumhue.identity, which takes the identity permission.
• identity_refreshed follows each refresh of the sign-in, the first right after identity_signed_in, and when the workstation takes up a sign-in made in another window or tab or with datumhue login. Read the account again then: its name, email and claims may have changed.
• identity_sign_in_failed says why in error_kind: "cancelled" when the sign-in was closed, "declined" when your app's request was refused, and other kinds for a provider or network failure. error_message is a sentence to show.
• identity_signed_out follows identity.sign_out, and a sign-out in another window or tab of the workstation.
• After a restart, someone may already be signed in: identity_refreshed announces them once their sign-in has refreshed.

Who starts the sign-in

Only the root app, usually the window manager, starts a sign-in itself. When any other app calls identity.sign_in or identity.sign_out, the app that started it hears an app_identity_sign_in_request or an app_identity_sign_out_request event, and decides.

A window manager answers a sign-in request through the event's request. SignInRequest:accept starts the sign-in the app asked for, or, in a window manager that is not the root app, passes the request on to its own parent. SignInRequest:decline tells that app alone, as identity_sign_in_failed with error_kind "declined". A request dropped without an answer is declined too.

One sign-in runs at a time. The root app's identity.sign_in while one runs replaces it and opens the sign-in page again, and identity.cancel_sign_in ends it as "cancelled".

Your app never sees the credential

When a web service needs the signed-in person's credential, the deployment attaches it to your app's requests through an HTTP mount (Call a web API).

See also

• Write a window manager or launcher, for answering requests from the apps you start.
• Messages, events and shared state, for the events your app hears.
• Call a web API

Reference used on this page: datumhue.identity datumhue.events datumhue.ui.root UiElement:label datumhue.events.on UiElement.text datumhue.identity.name datumhue.identity.email datumhue.identity.sub datumhue.identity.is_signed_in datumhue.identity.sign_in datumhue.identity.issuer datumhue.identity.claims datumhue.identity.sign_out SignInRequest:accept SignInRequest:decline datumhue.identity.cancel_sign_in