captive agents

summary

this template/example enables creation of "captive agents", where users can login to a gall agent with an urbit ID through an urbit oauth2 server. users are not required to have a running arvo to use their urbit ID with captive agents.

urbit sso server

https://github.com/urbit/sso

installation

• clone this repo
• |new-desk %sample
• |mount %sample
• cp -r /[repo]/desk/* /[pier]/sample/
• |commit %sample
• |install our %sample

sso setup

• login to the sso server
• click 'manage your applications'
• register a 'new application'
• the 'UID', 'secret' and 'callback url' will be used as part of a sso-config

sso-config

=sso -build-file /=sample=/sur/sso/hoon
=cig ^-  config:sso
:*  client-uid='...........................................'
    client-secret='...........................................'
    callback-url='http://localhost:8080/apps/sample/callback'
    sso-site='http://localhost:3000'
    authorize-path='/oauth/authorize'
    token-path='/oauth/token'
    info-path='/oauth/token/info'
==
:sample &sso-config cig

CORS

CORS will need to be approved for the sso server address with either

• |cors-approve 'http://localhost:3000'
• [%pass /eyre %arvo %e %approve-origin sso-site.cig]

how it works

• the user begins logging in by clicking a link containing a handful of paramaters required by the sso server, and an arbitrary state
• the user authenticates, and is redirected to the callback url, with code and state query parameters
• the callback page redirects appropriately, possibly making use of state
• the code is then used to request a token from the sso server
• the sso server responds with a token, which is used to request info
• the sso server responds with info, containing the user's urbit ID
• the agent stores a sessions map of eyre comet ID to the urbit ID provided by the sso server