# Device Registrar Service Guide

To view the device registrar APIs, please visit the [NCR Edge Wiki](https://wiki.edge-infra.dev/edge/components/device-registrar/api/)

## Local Dev setup

Start the server on kind cluster
```bash
# start a fresh kind cluster
just hack/kind/reset
# deploy cert manager
just cmd/edge/device-registrar/cert-manager
# deploy EdgeID
just cmd/edge/iam/kind
# deploy device-registrar service
just cmd/edge/device-registrar/kind
```
Then the service will be available at localhost:8080


## Flows
### Pre-reqs
1. Create an externalApplication CR on the cluster. The CRD definition can be found [here](../../../config/pallets/edge/device-registrar/base/crds/device-registrar.edge.ncr.com_externalapplications.yaml).
Below is an example:
```yaml
apiVersion: device-registrar.edge.ncr.com/v1alpha1
kind: ExternalApplication
metadata:
  name: connected-associates
  namespace: device-registrar-clients # the CR must be created in this namespace
spec:
  ID: "123e4567-e89b-12d3-a456-426614174000"
  description: "Connected associates mobile application definition"
  clientTemplate:
    apiVersion: iam.edge-infra.dev/v1alpha1
    kind: Client
    metadata:
      name: connected-associates-client
      labels:
        app: example
      annotations:
        description: "Example client for demonstration purposes"
    spec:
      audience:
      - "example-audience"
      clientName: "Connected Associates"
      grantTypes:
      - "authorization_code"
      printBarcodeTypes:
      - "QR"
      printBarcodeUri: "https://example.com/print-barcode"
      redirectUris:
      - "https://example.com/callback"
      responseModes:
      - "query"
      responseTypes:
      - "code"
      roles:
      - "user"
      scope: "openid profile email"
      secretName: "example-client-secret"
```
2. Configure discovery endpoint for the workload:
Include an discovery CR as part of the workload helm chart.
```yaml
apiVersion: device-registrar.edge.ncr.com/v1alpha1
kind: Discovery
metadata:
  name: javis-config-discovery
  namespace: jarvis-namespace
spec:
  name: jarvis # well-known service name
  url: https://jarvis.store.ncr.corp/config
```

### Simplified bootstrap flow

![Simplified Flow](./doc/simplified-flow.png)
#### To start a pairing process:
Locally
```bash
curl -X POST http://localhost:8080/pair   
```
In store
```bash
curl -X POST http://device-registrar-svc.device-registrar/pair   
```
which returns: 
```bash
{"connectURL":"https://edge-bootstrap.store.ncr.corp/connect/D46EX2C6HBGSLXG","hostMapping":{"host":"edge-bootstrap.store.ncr.corp","vip":"10.10.11.2"}}
```

#### To connect a device:
Locally
```bash
# '{
#   "device": {
#     "name": "test-device-name",         # required
#     "description": "my test device",    # optional
#     "serialNumber": "DSFE7DSCXX90"      # required
#   },
#   "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]  # required
# }'   
curl -X POST http://localhost:8080/connect/D46EX2C6HBGSLXG -H "Content-Type: application/json" -d '{
  "device": {
    "name": "test-device-name", 
    "description": "my test device", 
    "serialNumber": "DSFE7DSCXX90" 
  },
  "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]
}'   
```
In store
```bash
# '{
#   "device": {
#     "name": "test-device-name",         # required
#     "description": "my test device",    # optional
#     "serialNumber": "DSFE7DSCXX90"      # optional
#   },
#   "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]  # required
# }'   
# run `kubectl get secret -n emissary emissary-ca -o jsonpath='{.data.ca\.crt}' | base64 -d` to extract the ca cert
# save output to ca.cert.pem
curl --cacert ca.cert.pem -X POST https://edge-bootstrap.store.ncr.corp/connect/D46EX2C6HBGSLXG -H "Content-Type: application/json" -d '{
  "device": {
    "name": "test-device-name", 
    "description": "my test device", 
    "serialNumber": "DSFE7DSCXX90" 
  },
  "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]
}'   
```
which returns: 
```bash
{"applications":[{"id":"123e4567-e89b-12d3-a456-426614174000","name":"connected-associates","config":{"clientID":"7903dbf3-defb-448e-a457-c3217642523b","clientSecret":"fH4FeMcZhRjFDbePkiKWiCR7ER"}}],"deviceAuth":{"tls.crt":"REDACTED","tls.key":"REDACTED"},"hostMapping":{"host":"store.ncr.corp","vip":"10.10.11.2"}}
```

### Old bootstrap flow
![Old Flow](./doc/old-flow.png)
#### To list External Applications:
Locally
```bash
curl -X GET http://localhost:8080/applications
```
In store
```bash
curl -X GET http://device-registrar-svc.device-registrar/applications
```
which returns:
```bash
[{"id":"123e4567-e89b-12d3-a456-426614174000","name":"connected-associates","description":"Connected associates mobile application definition"}]
```

and you can also see the CRD:
```bash
kubectl get extapp -A
NAMESPACE                  NAME                   ID                                     DESCRIPTION                                          AGE
device-registrar-clients   connected-associates   123e4567-e89b-12d3-a456-426614174000   Connected associates mobile application definition   39s
```


#### To register a device:
Locally
```bash
curl -X POST http://localhost:8080/register -H "Content-Type: application/application/json" -d '{
  "device": {
    "name": "test-device-name-old", 
    "description": "my test device", 
    "serialNumber": "DSFE7DSCXX90" 
  },
  "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]
}'
```
In store
```bash
curl -X POST http://device-registrar-svc.device-registrar/register -H "Content-Type: application/application/json" -d '{
  "device": {
    "name": "test-device-name-old", 
    "description": "my test device", 
    "serialNumber": "DSFE7DSCXX90" 
  },
  "applicationIDs": ["123e4567-e89b-12d3-a456-426614174000"]
}' 
```
which returns: 
```bash
{"bootstrapURL":"https://edge-bootstrap.store.ncr.corp/bootstrap/F7RAXZXBFZQRPAU","hostMapping":{"host":"edge-bootstrap.store.ncr.corp","vip":"10.10.11.2"}}
```

#### To bootstrap a device:
Locally
```bash
curl -X GET http://localhost:8080/bootstrap/F7RAXZXBFZQRPAU
```
In store
```bash
# run `kubectl get secret -n emissary emissary-ca -o jsonpath='{.data.ca\.crt}' | base64 -d` to extract the ca cert
# save output to ca.cert.pem
curl --cacert ca.cert.pem -X GET https://edge-bootstrap.store.ncr.corp/bootstrap/F7RAXZXBFZQRPAU
```
which returns:
```bash
{"applications":[{"id":"123e4567-e89b-12d3-a456-426614174000","name":"connected-associates","config":{"clientID":"e00a1c4b-2bdc-450b-8fc6-9b10cce3869f","clientSecret":"bnTV~gAZj.CkkyXVUpND~ks4wE"}}],"deviceAuth":{"tls.crt":"REDACTED","tls.key":"REDACTED"},"hostMapping":{"host":"store.ncr.corp","vip":"10.10.11.2"}}
```

### Service discovery
#### To discover configuration endpoint for a service:
Locally
```bash
curl -X GET "http://localhost:8080/discover/jarvis" \
  -H "X-Client-DN: OU=urn:storeID:my-store-id+OU=urn:deviceName:my-test-device+OU=urn:SN:DSFE7DSCXX90"
```
In store
```bash
# run `kubectl get secret -n emissary emissary-ca -o jsonpath='{.data.ca\.crt}' | base64 -d` to extract the ca cert
# save output to ca.cert.pem
# use deviceAuth."tls.crt" from /connect API response
# save output to tls.cert
# use deviceAuth."tls.key" from /connect API response
# save output to tls.key
curl --cert tls.crt --key tls.key --cacert ca.cert.pem -X GET "https://edge.store.ncr.corp/discover/jarvis"
```
which returns:
```bash
{"name":"jarvis","url":"https://jarvis.store.ncr.corp/config"}
```
The API will look for the well-known service name in the request path e.g. jarvis. If the corresponding discovery CR is not found, the API will return 
```bash
{"name":"jarvis","url":null}
```

### Additional APIs

#### Delete External Application

Locally:
```
curl -X DELETE http://localhost:8080/applications/[external-application-id]
```

In store:
```
curl -X DELETE http://device-registrar-svc.device-registrar/applications/[external-application-id]
```
which returns a `204` upon successful deletion.

Example: 
```
curl -v -X DELETE http://localhost:8080/applications/123e4567-e89b-12d3-a456-426614174000
```

#### To Delete External Device
Locally
```bash
curl -X DELETE http://localhost:8080/devices/test-device-name
```
In store
```bash
curl -X DELETE http://device-registrar-svc.device-registrar/devices/test-device-name
```

## CRDs
### To see all crds:
```bash
kubectl api-resources --api-group=device-registrar.edge.ncr.com
NAME                   SHORTNAMES   APIVERSION                               NAMESPACED   KIND
devicebindings         devb         device-registrar.edge.ncr.com/v1alpha1   true         DeviceBinding
discoveries                         device-registrar.edge.ncr.com/v1alpha1   true         Discovery
externalapplications   extapp       device-registrar.edge.ncr.com/v1alpha1   true         ExternalApplication
externaldevices        extdev       device-registrar.edge.ncr.com/v1alpha1   true         ExternalDevice
```

## Generating Swagger UI Docs
### To view the docs locally

```
just cmd/edge/device-registrar/docs
```

### To generate docs:
```
just cmd/edge/device-registrar/gen-docs
```