RFC: Simple & automatic host registration WF

Development RFCs
52

Case 3: Vanilla Foreman with registration done through proxy

sequenceDiagram
    autonumber
    Participant Foreman
    Participant Proxy
    Participant Client

    Client->>Proxy: GET $proxy_url/register
    Proxy->>Foreman: GET $foreman_url/register?url=$proxy_url
    Foreman->>Proxy: GRT containing curl -X POST $proxy_url/register | sh
    Proxy->>Client: GRT containing curl -X POST $proxy_url/register | sh
    Client->>Proxy: POST $proxy_url/register
    Proxy->>Foreman: POST $foreman_url/register?url=$proxy_url
    Foreman->>Proxy: HRT with curl $proxy_url/built
    Proxy->>Client: HRT with curl $proxy_url/built
    Client->>Proxy: POST $proxy_url/built
    Proxy->>Foreman: POST $foreman_url/built

case3
case31142×621 43.4 KB

Steps in more details

  1. client contacts the proxy to initiate the process.
  2. proxy’s registration module computes proxy’s url based on the incoming request (more details later). It contacts Foreman at the $foreman_url based on the foreman_url proxy setting. Besides forwarding all parameters and headers client sent in request 1, it also adds url parameter.
  3. Foreman realizes that custom url was passed, so instead of using $foreman_url, it generates HRT curl with the hostname being a value of url parameter. For example if the client called https://proxy.example.com:8443/register, Foreman will receive https://proxy.example.com:8443 as url and inside of GRT, it will render curl -X POST https://proxy.example.com:8443/register.
  4. client gets the GRT and executes it, once it hits the HRT request, it continues with step 5
  5. proxy does the same as in step 3, forwards the request to Foreman, but tells it to use a different url for additional requests
  6. Foreman registers the host and renders HRT for it, again using params[:url] || foreman_url('built') logic, resulting in HRT which will call home through proxy.
  7. HRT template makes it to the proxy
  8. HRT template makes it to the client
  9. standard proxying of informing about host being built, no url magic needed here
  10. Foreman turns host into built, hooray

How proxy determines $proxy_url in steps 2 and 6?
Proxy looks at request.env['REQUEST_URI'] which contains the URL that client used in order to contact the proxy. In some edge cases, it may not be hostname -f of the proxy. It may not be the url of the proxy in Foreman. But it’s something we know client can resolve and talk to. The whole logic is request.env['REQUEST_URI']&.split('/register')&.first meaning we still keep the information about scheme, fqdn and port that was used.

Authentication of requests
GRT contains JWT that’s used to authenticate the request in step 5. Given it’s passed as a custom header, it gets automatically proxied in step 6. Foreman verifies the signature.

HRT contains the build token that is used to authenticate the POST /built after the execution of HRT is done. Please don’t ask for replacing this with JWT in Foreman 2.3 :slight_smile:

Authorization
JWT is tied to the user account, so HRT rendering happens under that account permissions. The fact the user knows build token means he had the permission to created (register) the host. We trust he or she can switch this flag without proper authorization. This is the well known concept from provisioning, where token knowledge is enough to flip the build mode.

I hope this helps, questions please. Also once you’re happy with the design for case 3, ACK would be great at least from the same group.