k-space/dex
Archived
10
0
Fork 0
Code Issues Pull Requests Packages Projects Activity

Update api documentation

Browse Source
This commit is contained in:
Mark Sagi-Kazar 2020-07-01 14:33:22 +02:00
parent e84682d7b9
commit 1b2ab6fa35
No known key found for this signature in database
GPG Key ID: 34CC109EB5ED1C2A
1 changed files with 60 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
Documentation/api.md
View File

@ -1,47 +1,50 @@
# The dex API # The Dex API
Dex provides a [gRPC][grpc] service for programmatic modification of dex's state. The API is intended to expose hooks for management applications and is not expected to be used by most installations. Dex provides a [gRPC](http://www.grpc.io/) service for programmatic modification of dex's state.
The API is intended to expose hooks for management applications and is not expected to be used by most installations.
This document is an overview of how to interact with the API. This document is an overview of how to interact with the API.
## Configuration ## Configuration
Admins that wish to expose the gRPC service must add the following entry to the dex config file. This option is off by default. Admins that wish to expose the gRPC service must add the following entry to the dex config file. This option is off by default.
``` ```yaml
grpc: grpc:
# Cannot be the same address as an HTTP(S) service. # Cannot be the same address as an HTTP(S) service.
addr: 127.0.0.1:5557 addr: 127.0.0.1:5557
# Server certs. If TLS credentials aren't provided dex will run in plaintext (HTTP) mode. # Server certs. If TLS credentials aren't provided dex will run in plaintext (HTTP) mode.
tlsCert: /etc/dex/grpc.crt tlsCert: /etc/dex/grpc.crt
tlsKey: /etc/dex/grpc.key tlsKey: /etc/dex/grpc.key
# Client auth CA. # Client auth CA.
tlsClientCA: /etc/dex/client.crt tlsClientCA: /etc/dex/client.crt
# enable reflection # enable reflection
reflection: true reflection: true
``` ```
## Generating clients
gRPC is a suite of tools for generating client and server bindings from a common declarative language. The canonical schema for dex's API can be found in the source tree at [`api/api.proto`][api-proto]. Go bindings are generated and maintained in the same directory for internal use. ## Clients
To generate a client for your own project install [`protoc`][protoc], install a protobuf generator for your project's language, and download the `api.proto` file. An example for a Go project: gRPC is a suite of tools for generating client and server bindings from a common declarative language.
The canonical schema for Dex's API can be found in the source tree at [`api/v2/api.proto`](../api/v2/api.proto).
Go bindings are generated and maintained in the same directory for both public and internal use.
```
# Install protoc-gen-go.
$ go get -u github.com/golang/protobuf/{proto,protoc-gen-go}
# Download api.proto for a given version. ### Go
$ DEX_VERSION=v2.0.0-alpha.5
$ wget https://raw.githubusercontent.com/dexidp/dex/${DEX_VERSION}/api/api.proto
# Generate the Go client bindings. A Go project can import the API module directly, without having to import the entire project:
$ protoc --go_out=import_path=dexapi:. api.proto
```bash
go get github.com/dexidp/dex/api/v2
``` ```
Client programs can then be written using the generated code. A Go client which uses dex's internally generated code might look like the following: The client then can be used as follows:
``` ```go
package main package main
import ( import (
@ -88,30 +91,56 @@ func main() {
} }
``` ```
A clear working example of the Dex gRPC client can be found [here](../examples/grpc-client/README.md). A clear working example of the Dex gRPC client for Go can be found [here](../examples/grpc-client/README.md).
### Other languages
To generate a client for your own project install [`protoc`](https://github.com/google/protobuf/releases),
install a protobuf generator for your project's language, and download the `api.proto` file.
Here is an example:
```bash
# Download api.proto for a given version.
$ DEX_VERSION=v2.24.0
$ wget https://raw.githubusercontent.com/dexidp/dex/${DEX_VERSION}/api/v2/api.proto
# Generate the client bindings.
$ protoc [YOUR LANG PARAMS] api.proto
```
Client programs can then be written using the generated code.
## Authentication and access control ## Authentication and access control
The dex API does not provide any authentication or authorization beyond TLS client auth. The Dex API does not provide any authentication or authorization beyond TLS client auth.
Projects that wish to add access controls on top of the existing API should build apps which perform such checks.
For example to provide a "Change password" screen, a client app could use Dex's OpenID Connect flow to authenticate an end user,
then call Dex's API to update that user's password.
Projects that wish to add access controls on top of the existing API should build apps which perform such checks. For example to provide a "Change password" screen, a client app could use dex's OpenID Connect flow to authenticate an end user, then call dex's API to update that user's password.
## dexctl? ## dexctl?
Dex does not ship with a command line tool for interacting with the API. Command line tools are useful but hard to version, easy to design poorly, and expose another interface which can never be changed in the name of compatibility. Dex does not ship with a command line tool for interacting with the API.
Command line tools are useful but hard to version, easy to design poorly,
and expose another interface which can never be changed in the name of compatibility.
While the Dex team would be open to re-implementing `dexctl` for v2 a majority of the work is writing a design document,
not the actual programming effort.
While the dex team would be open to re-implementing `dexctl` for v2 a majority of the work is writing a design document, not the actual programming effort.
## Why not REST or gRPC Gateway? ## Why not REST or gRPC Gateway?
Between v1 and v2, dex switched from REST to gRPC. This largely stemmed from problems generating documentation, client bindings, and server frameworks that adequately expressed REST semantics. While [Google APIs][google-apis], [Open API/Swagger][open-api], and [gRPC Gateway][grpc-gateway] were evaluated, they often became clunky when trying to use specific HTTP error codes or complex request bodies. As a result, v2's API is entirely gRPC. Between v1 and v2, Dex switched from REST to gRPC. This largely stemmed from problems generating documentation,
client bindings, and server frameworks that adequately expressed REST semantics.
While [Google APIs](https://github.com/google/apis-client-generator), [Open API/Swagger](https://openapis.org/),
and [gRPC Gateway](https://github.com/grpc-ecosystem/grpc-gateway) were evaluated,
they often became clunky when trying to use specific HTTP error codes or complex request bodies.
As a result, v2's API is entirely gRPC.
Many arguments _against_ gRPC cite short term convenience rather than production use cases. Though this is a recognized shortcoming, dex already implements many features for developer convenience. For instance, users who wish to manually edit clients during testing can use the `staticClients` config field instead of the API. Many arguments _against_ gRPC cite short term convenience rather than production use cases.
Though this is a recognized shortcoming, Dex already implements many features for developer convenience.
[grpc]: http://www.grpc.io/ For instance, users who wish to manually edit clients during testing can use the `staticClients` config field instead of the API.
[api-proto]: ../api/api.proto
[protoc]: https://github.com/google/protobuf/releases
[protoc-gen-go]: https://github.com/golang/protobuf
[google-apis]: https://github.com/google/apis-client-generator
[open-api]: https://openapis.org/
[grpc-gateway]: https://github.com/grpc-ecosystem/grpc-gateway