Ubuntu Swagger如何处理认证

Defining Authentication Methods in OpenAPI Specification
The first step in handling authentication in Ubuntu Swagger (OpenAPI) is to define the authentication mechanism in your OpenAPI definition file (typically swagger.yaml or openapi.json). Common methods include OAuth2, API keys, and Basic Authentication. For example, to use OAuth2 with the authorization code flow, you would add a securitySchemes section:

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access

For API key authentication (passed in the header), the configuration would look like this:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

These definitions specify how clients should authenticate with your API.

Applying Authentication to API Endpoints
Once the authentication method is defined, you need to apply it to the endpoints that require protection. This is done using the security field in the endpoint definition. For instance, to protect a /protected-resource GET endpoint with the OAuth2 scheme defined earlier:

paths:
  /protected-resource:
    get:
      security:
        - OAuth2: []  # Requires OAuth2 authentication
      responses:
        '200':
          description: Successful response

If you want the authentication to apply globally to all endpoints, you can add a security field at the root level of the OpenAPI document.

Configuring Swagger UI for Authentication
Swagger UI needs to be set up to handle the authentication flow. For OAuth2, you must configure the oauth2RedirectUrl (the callback URL where the authorization server redirects after user login) when initializing Swagger UI in your Express app:

const ui = SwaggerUIBundle({
  url: "path/to/your/swagger.json",
  dom_id: '#swagger-ui',
  oauth2RedirectUrl: "https://yourapp.com/oauth2-redirect", // Required for OAuth2
  presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
  plugins: [SwaggerUIBundle.plugins.DownloadUrl],
  layout: "StandaloneLayout"
});

For API key authentication, Swagger UI will automatically add an input field for the API key in the UI. Users can enter the key, and it will be included in the X-API-KEY header for all requests.

Implementing Backend Authentication Logic
The backend must validate the authentication credentials provided by the client. For JWT (JSON Web Tokens), a common approach is to create a middleware that verifies the token’s signature and extracts user information. Here’s an example using the jsonwebtoken library in Node.js:

const jwt = require('jsonwebtoken');
const secretKey = 'your-secret-key'; // Replace with your actual secret key

const authenticateToken = (req, res, next) => {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1]; // Extract token from "Bearer <token>"
  if (!token) return res.sendStatus(401); // No token provided
  
  jwt.verify(token, secretKey, (err, user) => {
    if (err) return res.sendStatus(403); // Invalid token
    req.user = user; // Attach user info to the request object
    next();
  });
};

// Protect an endpoint with the middleware
app.get('/api/resource', authenticateToken, (req, res) => {
  res.json({ message: 'This is a protected resource', user: req.user });
});

For OAuth2, you need to integrate with an authorization server (e.g., Keycloak, Auth0) to validate the access token issued during the OAuth2 flow.

Generating and Using Tokens (for OAuth2/JWT)
To test OAuth2 authentication, you need an endpoint to generate tokens (e.g., a /login endpoint). Here’s an example using Node.js and Express:

app.post('/login', (req, res) => {
  const { username, password } = req.body;
  // Replace with your actual user authentication logic
  if (username === 'admin' && password === 'password') {
    const token = jwt.sign({ username }, secretKey, { expiresIn: '1h' }); // Generate token
    res.json({ token });
  } else {
    res.status(401).json({ message: 'Invalid credentials' });
  }
});

Users can call this endpoint with their credentials to obtain a token, which they then use to access protected resources by including it in the Authorization header (e.g., Authorization: Bearer <token>).

Testing Authentication
After setting up the OpenAPI definition, Swagger UI, and backend logic, test the authentication flow:

1. Open Swagger UI in your browser (e.g., http://localhost:3000/api-docs).
2. Navigate to the protected endpoint (e.g., /protected-resource).
3. If using OAuth2, click the “Authorize” button, log in with your credentials, and grant permissions.
4. If using API keys, enter the key in the provided input field.
5. Call the endpoint and verify that the response is successful (status code 200) and includes the expected data.
6. Test with invalid credentials to ensure the endpoint returns a 401 (Unauthorized) or 403 (Forbidden) status code.