github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/docs/tutorial/authentication/README.md (about)

     1  # Authentication sample
     2  
     3  The full code of this example is [here][example_code].
     4  
     5  Define the following security scheme (in `swagger.yml` specification document):
     6  
     7  ```yaml
     8  securityDefinitions:
     9    key:
    10      type: apiKey
    11      in: header
    12      name: x-token
    13  ```
    14  
    15  Specify the following security requirements for all endpoints: so by default,
    16  all endpoints use the API key auth.
    17  
    18  ```yaml
    19  security:
    20    - key: []
    21  ```
    22  
    23  Add security princial model definition:
    24  
    25  ```yaml
    26  definitions:
    27  
    28  ...
    29  
    30    principal:
    31      type: string
    32  ```
    33  
    34  Generate the code with a security principal:
    35  
    36  ```shell
    37  swagger generate server -A AuthSample -P models.Principal -f ./swagger.yml
    38  ```
    39  
    40  Edit the ./restapi/configure_auth_sample.go file
    41  
    42  ```go
    43  func configureAPI(api *operations.AuthSampleAPI) http.Handler {
    44  	// configure the api here
    45  	api.ServeError = errors.ServeError
    46  
    47  	// Set your custom logger if needed. Default one is log.Printf
    48  	// Expected interface func(string, ...interface{})
    49  	//
    50  	// Example:
    51  	api.Logger = log.Printf
    52  
    53  	api.JSONConsumer = runtime.JSONConsumer()
    54  
    55  	api.JSONProducer = runtime.JSONProducer()
    56  
    57  	// Applies when the "x-token" header is set
    58  	api.KeyAuth = func(token string) (*models.Principal, error) {
    59  		if token == "abcdefuvwxyz" {
    60  			prin := models.Principal(token)
    61  			return &prin, nil
    62  		}
    63  		api.Logger("Access attempt with incorrect api key auth: %s", token)
    64  		return nil, errors.New(401, "incorrect api key auth")
    65  	}
    66  
    67  	api.CustomersCreateHandler = customers.CreateHandlerFunc(func(params customers.CreateParams, principal *models.Principal) middleware.Responder {
    68  		return middleware.NotImplemented("operation customers.Create has not yet been implemented")
    69  	})
    70  	api.CustomersGetIDHandler = customers.GetIDHandlerFunc(func(params customers.GetIDParams, principal *models.Principal) middleware.Responder {
    71  		return middleware.NotImplemented("operation customers.GetID has not yet been implemented")
    72  	})
    73  
    74  	api.ServerShutdown = func() {}
    75  
    76  	return setupGlobalMiddleware(api.Serve(setupMiddlewares))
    77  }
    78  ```
    79  
    80  Run the server:
    81  
    82  ```shell
    83  go run ./cmd/auth-sample-server/main.go --port 35307
    84  ```
    85  
    86  Exercise auth:
    87  
    88  ```shellsession
    89  ± ivan@avalon:~  
    90   » curl -i -H 'Content-Type: application/keyauth.api.v1+json' -H 'X-Token: abcdefuvwxyz' http://127.0.0.1:35307/api/customers
    91  ```
    92  ```http
    93  HTTP/1.1 501 Not Implemented
    94  Content-Type: application/keyauth.api.v1+json
    95  Date: Fri, 25 Nov 2016 19:14:14 GMT
    96  Content-Length: 57
    97  
    98  "operation customers.GetID has not yet been implemented"
    99  ```
   100  ```shellsession
   101  ± ivan@avalon:~  
   102   » curl -i -H 'Content-Type: application/keyauth.api.v1+json' -H 'X-Token: abcdefu' http://127.0.0.1:35307/api/customers
   103  ```
   104  ```http
   105  HTTP/1.1 401 Unauthorized
   106  Content-Type: application/keyauth.api.v1+json
   107  Date: Fri, 25 Nov 2016 19:16:49 GMT
   108  Content-Length: 47
   109  
   110  {"code":401,"message":"incorrect api key auth"}
   111  ```
   112  
   113  [example_code]: https://github.com/thetreep/go-swagger/tree/master/examples/authentication