Open Government, New Zealand Authentication: Methods & Security

Authentication overview

Access to Open Government, New Zealand's APIs requires robust authentication to ensure data security and maintain the integrity of government services. The platform follows established industry standards to provide secure and manageable access for developers and applications. This approach helps protect sensitive information while enabling efficient integration with public datasets and digital services. All communication with Open Government APIs is encrypted using Transport Layer Security (TLS) version 1.2 or higher, providing a secure channel for credential and data exchange.

The authentication framework is designed to support various integration scenarios, from server-to-server communication to user-authorized applications. Developers are encouraged to select the authentication method that best suits their application's architecture and security requirements, prioritizing methods that offer delegated authorization when user context is involved.

Supported authentication methods

Open Government, New Zealand provides two primary authentication mechanisms:

1. OAuth 2.0: An industry-standard protocol for delegated authorization, allowing third-party applications to access user resources without exposing user credentials. It is recommended for applications that act on behalf of a user. The platform supports the Authorization Code grant flow for web applications and the Client Credentials grant flow for server-to-server applications. For a comprehensive understanding of OAuth 2.0, consult the official OAuth 2.0 specification.
2. API Keys: A simpler authentication method suitable for applications that do not require user delegation and primarily access public or application-specific resources. API keys are long, unique strings that identify the calling application. They are typically passed as a header or query parameter in API requests.

Comparison of Authentication Methods

Getting your credentials

To access Open Government, New Zealand APIs, you must first register your application and obtain the necessary credentials through the official Developer Portal. The process typically involves these steps:

1. Register a Developer Account: If you don't already have one, create an account on the Open Government, New Zealand Developer Portal. This account will be linked to all your applications and credentials.
2. Register Your Application: Navigate to the 'Applications' section within the Developer Portal and register a new application. You will need to provide details such as your application's name, description, and, for OAuth 2.0 applications, a redirect URI. The redirect URI is where the authorization server sends the user back after they have granted permission to your application.
3. Obtain Client ID and Client Secret (for OAuth 2.0): Upon successful application registration, the Developer Portal will provide you with a unique Client ID and Client Secret. The Client ID identifies your application, and the Client Secret is a confidential key used to authenticate your application to the authorization server. It is crucial to keep your Client Secret confidential and never embed it directly in client-side code.
4. Generate API Keys (if applicable): If your application uses API key authentication, you can generate one or more API keys directly from your application's settings within the Developer Portal. You may also be able to assign specific permissions or scopes to each key, depending on the API's design.
5. Review Scopes: For OAuth 2.0, understand the necessary scopes your application requires. Scopes define the specific permissions your application is requesting from the user (e.g., read public data, access specific user profile information). Only request the minimum necessary scopes to adhere to the principle of least privilege. More details on scope implementation can be found in the AWS Cognito documentation on OAuth 2.0 scopes.

The Developer Portal serves as the central hub for managing all your API access credentials, monitoring API usage, and accessing documentation.

Authenticated request example

This example demonstrates how to make an authenticated request using an API key. For OAuth 2.0, the process involves an initial authorization flow to obtain an access token, which is then used similarly to an API key in the Authorization header.

Example using an API Key (in HTTP Header):

Assuming you have an API key named YOUR_API_KEY, you would include it in the X-Api-Key header (or a similar custom header specified by the API) of your HTTP request.

GET /api/v1/public-datasets/example HTTP/1.1
Host: api.govt.nz
X-Api-Key: YOUR_API_KEY

Example using an OAuth 2.0 Access Token (in Authorization Header):

After successfully completing an OAuth 2.0 flow and obtaining an access_token, you would include it in the Authorization header using the Bearer scheme.

GET /api/v1/user-data/profile HTTP/1.1
Host: api.govt.nz
Authorization: Bearer YOUR_ACCESS_TOKEN

In both examples, replace api.govt.nz with the actual API endpoint and /api/v1/public-datasets/example or /api/v1/user-data/profile with the specific API path you intend to call. The exact header name for API keys might vary; refer to the specific API's documentation for precise details.

Security best practices

Adhering to security best practices is essential when integrating with Open Government, New Zealand APIs to protect your application, user data, and the integrity of government services. The following guidelines are strongly recommended:

• Protect Your Credentials:
  • Client Secrets and API Keys: Never hardcode client secrets or API keys directly into your application's source code, especially for client-side applications. Store them securely using environment variables, dedicated secret management services (e.g., AWS Secrets Manager, Azure Key Vault, Google Secret Manager), or secure configuration files.
  • Access Tokens: Treat OAuth 2.0 access tokens as sensitive data. Store them securely and transmit them only over HTTPS.
• Use HTTPS/TLS: Always ensure that all communication with Open Government APIs occurs over HTTPS (TLS 1.2 or higher). This encrypts data in transit, protecting credentials and data from eavesdropping.
• Implement Token Refresh (OAuth 2.0): For OAuth 2.0, utilize refresh tokens to obtain new access tokens. Access tokens typically have short lifespans, minimizing the window of opportunity for compromise. Store refresh tokens securely and revoke them if compromised.
• Principle of Least Privilege: Request and grant only the minimum necessary permissions (scopes) for your application to function. This limits the potential impact if your application's credentials are compromised.
• Regular Key Rotation: Periodically rotate your API keys and OAuth 2.0 client secrets. This practice reduces the risk associated with long-lived credentials. Establish a schedule for rotation and automate the process where possible.
• Error Handling without Leaking Information: Configure your application's error handling to avoid exposing sensitive information (e.g., API keys, internal server details) in error messages that might be visible to end-users or logs that are not properly secured.
• Input Validation: Implement robust input validation for all data sent to Open Government APIs. This helps prevent common web vulnerabilities like injection attacks.
• Monitor API Usage: Regularly monitor your application's API usage for unusual patterns or suspicious activity that might indicate a compromise or misuse of your credentials.
• Secure Your Redirect URIs (OAuth 2.0): Ensure that your registered redirect URIs are specific and secure. Using localhost for development is acceptable, but for production, use a fully qualified domain name with HTTPS. Avoid generic redirect URIs that could be exploited. This is a critical security consideration, as highlighted by the IETF RFC 6749 on OAuth 2.0 Redirect URIs.
• Stay Updated: Keep your application's dependencies, libraries, and frameworks updated to patch known security vulnerabilities.